MCP Best Practices
Expose capabilities cleanly, safely, and predictably so AI clients can use them without guesswork.
Keep capabilities narrow
Each tool should do one understandable job. Narrow capabilities are easier for models to choose, easier to secure, and easier to test.
search_customers, get_customer, and update_customer_note over one broad manage_crm tool. Use clear schemas
Models are better at calling tools when inputs and outputs are explicit. Avoid asking the model to stuff everything into one free-form string.
Design for safety
Read-only tools can often run automatically. Write operations, payments, deletes, external messages, or production changes usually need stricter permission handling.
Separate read, write, destructive, and externally visible operations.
Ask for approval before actions with cost, risk, or irreversible effects.
Scope credentials, filters, time ranges, and resource ids as tightly as possible.
Make failures useful
A good MCP server returns errors the client can act on. Tell the agent whether it should retry, change input, ask the user, or stop.
Observe and test
Log how capabilities are used and build tests around both success and failure cases. MCP integrations become infrastructure, so treat them like production APIs.
- Test schema validation and permission failures.
- Track tool call frequency, latency, and error rates.
- Review transcripts where the model selected the wrong capability.
- Update descriptions when tool selection is unreliable.