MCP Best Practices

MCP Best Practices are a set of guidelines for developers to create high-quality servers and clients. Following these ensures a better user experience and robust agentic workflows.

Design Guidelines

• Atomic Tools: Create small, focused tools rather than large, monolithic ones. This helps the AI better understand when to call them.
• Idempotency: Ensure state-altering tools are idempotent to prevent errors during retries.
• Clear Descriptions: Provide detailed, descriptive names and descriptions for every tool and argument. This is the primary "UI" for the AI model.
• Error Handling: Return clear, actionable error messages. Instead of "Fetch failed", use "API Key invalid" or "Database connection timeout".
• Pagination: Always paginate large results to prevent transport crashes.

Security Practices

• Validation: Strictly validate all tool arguments according to the JSON Schema.
• Masking: Use PII masking for sensitive user data.

Questions & Answers

Why should developers prefer "Atomic Tools" over monolithic ones?

Atomic, focused tools are easier for AI models to understand and select correctly. Small tools reduce ambiguity and allow the model to compose complex workflows more reliably.

What is the "UI" of an MCP server for an AI model?

The "UI" consists of the descriptive names and detailed documentation provided for tools and their arguments. Clear descriptions are the primary way the AI learns how and when to use a tool.

How does pagination prevent transport crashes in MCP?

By breaking large results into manageable chunks (pages), pagination prevents the underlying communication channel (like stdio or SSE) from being overwhelmed by a single massive message, which could lead to timing out or crashing.