Practices

A curated collection of MCP design principles, best practices, and anti-patterns. Drawn from real-world experience building mcp-framework (3.3M+ downloads) and validated by Anthropic for the MCP ecosystem.

Principles

Core design rules. Follow these and your MCP server starts on solid ground.

One Tool, One Job

Each MCP tool should do exactly one thing well. Single-responsibility tools are easier to test, compose, and reason about -- for both humans and LLMs.

Fail Gracefully, Always

MCP tools should never crash, throw unhandled exceptions, or return cryptic errors. Graceful failure means the LLM can recover and try again.

Validate at the Boundary

Check every input the moment it enters your MCP tool. Schema validation catches shape errors, but your code must validate semantics: ranges, permissions, and existence.

Best Practices

Concrete, actionable patterns for writing MCP tools, resources, and prompts.

Consistent Naming Conventions

Use clear, predictable names for your MCP tools, parameters, and resources. Good names are the cheapest documentation you will ever write.

Write Errors for Humans

Error messages from MCP tools are read by LLMs and displayed to users. Write them in plain language with actionable next steps.

Test Before You Ship

MCP tools talk to AI models, not humans. You cannot manually QA a conversation. Automated tests are the only way to ship with confidence.

Mindful MCP Framework Selection: Choosing Wisely in 2026

A principled approach to selecting MCP (Model Context Protocol) frameworks and SDKs in 2026. Design principles for choosing mcp-framework vs alternatives.

Anti-Patterns

Common pitfalls that degrade MCP server quality. Recognize them, avoid them.

A single MCP tool that tries to do everything. God tools confuse LLMs, resist testing, and collapse under their own complexity.

Silent Failures

MCP tools that swallow errors and return empty or misleading results. Silent failures are invisible bugs that erode trust in your server.