The Model Context Protocol (MCP) has exploded roughly 1 year ago, everyone rushed to build MCP servers. The hype was real. Yet, most MCP servers disappoint. Most developers blame the protocol. The protocol feels like it's dying on social media.
\nBut enterprise adoption tells a different story. Companies are deploying MCP servers. The integrations are live. But the results? Disappointing. Why?
\nDevelopers treat MCP like a REST API wrapper. MCP is a User Interface for Agents. Different users, different design principles.
\nThe protocol works fine. The servers don't.
\nThis post breaks down why MCP servers fail, six best practices for building ones that work, and how Skills and MCP complement each other.
\nMCP (Model Context Protocol) provides a universal connection between LLMs and external tools, data sources, and services. Before MCP, every integration required custom connectors. MCP standardizes three primitives:
\nsearch_documents, create_issue)The idea behind MCP is to build your MCP server once, and use with any agent.
\nMCP servers are not thin wrappers around your existing API. A Good REST API is not a good MCP server. We assume just because LLMs are "smart", they can use APIs as a human would. Thats wrong.
\nREST API design principles advocate for composability, discoverability, flexibility, and stability. Small endpoints developers combine. Self-documenting schemas.
\nThese principles work for human developers. They don't work for AI agents. MCP is a User Interface for AI agents. Different users, different design principles.
\n| REST API Principles | \nDevelopers | \nAgents | \n
|---|---|---|
| Discovery | \nCheap (read docs once) | \nExpensive (schema in every request) | \n
| Composability | \nMix and match small endpoints | \nMulti-step tool calls, slow iteration | \n
| Flexibility | \nMany options > more flexibility | \nComplexity leads to hallucination | \n
Additionally, MCP servers are not data dump services. Throwing large scale raw data at an agent bloats its context window.
\nA Practical Example: Order Tracking
\nYou're building an agent that tracks orders.
\nAs a human developer, you read the API docs once, write a script calling GET /users, GET /orders, GET /shipments in sequence, debug it, deploy it.
A bad MCP server exposes those three endpoints as tools. The agent must load all three tool description, make 3 round-trips and stores all intermediate results in conversation history.
\nA good MCP server exposes one tool, track_order(email). The tool calls all three internally and returns "Order #12345 shipped via FedEx, arriving Thursday." Same outcome, one call, outcome oriented.
MCP is a User Interface for a non-human user. Same product thinking, different user.
\nTo fix your server, you need to curate the experience. Here are the six best practices for building a good MCP server.
\nTrap: Converting REST endpoints 1:1 into MCP tools.
\nFix: Design tools around what the user/agent wants to achieve.
\nDon't expose three separate tools for order status:
\nget_user_by_email()list_orders(user_id)get_order_status(order_id)This forces the agent to orchestrate three round-trips. Instead of three atomic tools, give the agent one high-level tool: track_latest_order(email). Do the orchestration in your code, not in the LLM's context window.
Trap: Using complex nested dictionaries or configuration objects as arguments.
\nFix: Top-level primitives and constrained types.
\n| ❌ Bad | \n✅ Good | \n
|---|---|
def search_orders(filters: dict) -> list | \ndef search_orders(email: str, status: Literal["pending", "shipped", "delivered"] = "pending", limit: int = 10) -> list | \n
| Agent guesses the structure | \nClear, typed, constrained | \n
| Hallucinates keys, misses required fields | \nLiteral constrains choices, defaults reduce decisions | \n
Trap: Empty docstrings, generic error messages.
\nFix: Every piece of text is part of the agent's context.
\nDocstrings are instructions. Specify:
\nError Messages are context too! If a tool call fails, don't throw a Python exception. Return a helpful string: "User not found. Please try searching by email address instead." The agent sees the error as an observation and uses your instruction to self-correct in the next turn.
\nTrap: Exposing everything your API can do. Returning everything the API returns.
\nFix: Design for discovery, not exhaustive exposure.
\nAgents operate under tight context constraints. Every tool description, every response payload, every error message, it all competes in the context window.
\nBuild for discovery. The agent should find the right tool quickly and get an actionable response.
\nTrap: Generic names like create_issue or send_message.
Fix: Service-prefixed, action-oriented names.
\nYour MCP server runs alongside others. If GitHub and Jira both have create_issue, the agent guesses. Pattern: {service}_{action}_{resource}. Examples: slack_send_message, linear_list_issues, sentry_get_error_details.
Note: Some MCP clients prefix tools with the server name automatically.
\nTrap: Returning hundreds of records.
\nFix: Paginate with metadata.
\nlimit parameter (default 20–50)has_more, next_offset, total_countYou're building an MCP server for Gmail. Here's how most developers approach it versus the agent-first design.
\nPython
\n# Reading an email requires 2 tools + understanding nested types\n ...\n ...\n \n# Sending an email requires base64-encoding a MIME message\n ... # raw = base64url RFC 2822\n \n# Creating a draft has nested message object\n ...\nProblems: Agent must construct {"raw": base64(...)} and parse nested payload.body.data. Generic names.
Python
\n# Reading: 2 flat tools with curated returns\n ...\n ...\n \n# Writing: Simple examples, not including cc, bcc.\n ...\nSkills package instructions, metadata, and resources that the agent uses when relevant. They're filesystem-based with progressive disclosure. Each skill has a name, description, which is part of the Model context. The Model/Agent can then decide to use the skill or not based on the given context.
\n| Level | \nWhen Loaded | \nToken Cost | \nContent | \n
|---|---|---|---|
| Metadata | \nStartup | \n~100 tokens | \nname and description from YAML | \n
| Instructions | \nWhen triggered | \n<5k tokens | \nSKILL.md body | \n
| Resources | \nAs needed | \nUnlimited | \nScripts via bash | \n
Skills don't add tool definitions directly, but can include scripts that run locally to provide capabilities similar to MCP servers. The difference is that skills leverage generic execution tools (like bash) rather than defining new tool schemas. Leading to potentially more steps and discovery needed. MCP provides a structured interfaces. The model gets parameter validation, typed responses.
Neither is better than the other. It depends on the use case and your preference. In company contexts, MCP servers shine when teams expose their own services. Skills complement this by teaching agents when and how to combine those tools for specific workflows. Use both.
\nWhen building an MCP Server you are not building infrastructure, you are building an interface for AI agents.
\nMCP is a User Interface for AI agents. Build it like one.
\nOther resources: Block's MCP Playbook, GitHub's Security Guide, FastMCP AI Engineering Summit.
\nThanks for reading! If you have any questions or feedback, please let me know on Twitter or LinkedIn.
\n", "content_markdown": "The Model Context Protocol (MCP) has exploded roughly 1 year ago, everyone rushed to build MCP servers. The hype was real. Yet, most MCP servers disappoint. Most developers blame the protocol. The protocol feels like it's dying on social media.\n\nBut enterprise adoption tells a different story. Companies are deploying MCP servers. The integrations are live. But the results? Disappointing. Why?\n\nDevelopers treat MCP like a REST API wrapper. MCP is a User Interface for Agents. Different users, different design principles.\n\n**The protocol works fine. The servers don't.**\n\nThis post breaks down why MCP servers fail, six best practices for building ones that work, and how Skills and MCP complement each other.\n\n## What is MCP?\n\nMCP (Model Context Protocol) provides a universal connection between LLMs and external tools, data sources, and services. Before MCP, every integration required custom connectors. MCP standardizes three primitives:\n\n- **Tools**: Functions the agent can call (`search_documents`, `create_issue`)\n- **Resources**: Data the agent can read (files, database records)\n- **Prompts**: Pre-built workflows the user or agent can invoke\n\nThe idea behind MCP is to build your MCP server once, and use with any agent.\n\n## What MCP is NOT\n\nMCP servers are not thin wrappers around your existing API. A Good REST API is not a good MCP server. We assume just because LLMs are \"smart\", they can use APIs as a human would. Thats wrong.\n\nREST API design principles advocate for composability, discoverability, flexibility, and stability. Small endpoints developers combine. Self-documenting schemas.\n\nThese principles work for human developers. They don't work for AI agents. MCP is a User Interface for AI agents. Different users, different design principles.\n\n| REST API Principles | Developers | Agents |\n| ------------------- | ------------------------------- | ------------------------------------- |\n| **Discovery** | Cheap (read docs once) | Expensive (schema in every request) |\n| **Composability** | Mix and match small endpoints | Multi-step tool calls, slow iteration |\n| **Flexibility** | Many options > more flexibility | Complexity leads to hallucination |\n\nAdditionally, MCP servers are not data dump services. Throwing large scale raw data at an agent bloats its context window.\n\n**A Practical Example: Order Tracking**\n\nYou're building an agent that tracks orders.\n\nAs a human developer, you read the API docs once, write a script calling `GET /users`, `GET /orders`, `GET /shipments` in sequence, debug it, deploy it.\n\nA bad MCP server exposes those three endpoints as tools. The agent must load all three tool description, make 3 round-trips and stores all intermediate results in conversation history.\n\nA good MCP server exposes one tool, `track_order(email)`. The tool calls all three internally and returns \"Order #12345 shipped via FedEx, arriving Thursday.\" Same outcome, one call, outcome oriented.\n\nMCP is a User Interface for a non-human user. Same product thinking, different user.\n\n## How to Build a Good MCP Server (Best Practices)\n\nTo fix your server, you need to curate the experience. Here are the six best practices for building a good MCP server.\n\n### 1\\. Outcomes, Not Operations\n\n**Trap:** Converting REST endpoints 1:1 into MCP tools.\n\n**Fix:** Design tools around what the user/agent wants to achieve.\n\nDon't expose three separate tools for order status:\n\n- `get_user_by_email()`\n- `list_orders(user_id)`\n- `get_order_status(order_id)`\n\nThis forces the agent to orchestrate three round-trips. Instead of three atomic tools, give the agent one high-level tool: `track_latest_order(email)`. Do the orchestration in your code, not in the LLM's context window.\n\n### 2\\. Flatten Your Arguments\n\n**Trap:** Using complex nested dictionaries or configuration objects as arguments.\n\n**Fix:** Top-level primitives and constrained types.\n\n| ❌ Bad | ✅ Good |\n| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |\n| `def search_orders(filters: dict) -> list` | `def search_orders(email: str, status: Literal[\"pending\", \"shipped\", \"delivered\"] = \"pending\", limit: int = 10) -> list` |\n| Agent guesses the structure | Clear, typed, constrained |\n| Hallucinates keys, misses required fields | `Literal` constrains choices, defaults reduce decisions |\n\n### 3\\. Instructions are Context\n\n**Trap:** Empty docstrings, generic error messages.\n\n**Fix:** Every piece of text is part of the agent's context.\n\nDocstrings are instructions. Specify:\n\n- When to use the tool (\"Use when the user asks about order status\")\n- How to format arguments (\"Email must be lowercase\")\n- What to expect back (\"Returns order ID and current status\")\n\nError Messages are context too! If a tool call fails, don't throw a Python exception. Return a helpful string: *\"User not found. Please try searching by email address instead.\"* The agent sees the error as an observation and uses your instruction to self-correct in the next turn.\n\n### 4\\. Curate Ruthlessly\n\n**Trap:** Exposing everything your API can do. Returning everything the API returns.\n\n**Fix:** Design for discovery, not exhaustive exposure.\n\nAgents operate under tight context constraints. Every tool description, every response payload, every error message, it all competes in the context window.\n\n- 5–15 tools per server.\n- One server, one job.\n- Delete unused tools.\n- Split by persona. (Admin/user)\n\nBuild for discovery. The agent should find the right tool quickly and get an actionable response.\n\n### 5\\. Name Tools for Discovery\n\n**Trap:** Generic names like `create_issue` or `send_message`.\n\n**Fix:** Service-prefixed, action-oriented names.\n\nYour MCP server runs alongside others. If GitHub and Jira both have `create_issue`, the agent guesses. Pattern: `{service}_{action}_{resource}`. Examples: `slack_send_message`, `linear_list_issues`, `sentry_get_error_details`.\n\nNote: Some MCP clients prefix tools with the server name automatically.\n\n### 6\\. Paginate Large Results\n\n**Trap:** Returning hundreds of records.\n\n**Fix:** Paginate with metadata.\n\n- Respect a `limit` parameter (default 20–50)\n- Return `has_more`, `next_offset`, `total_count`\n- Never load all results into memory\n\n## Practical Example: Gmail MCP Server\n\nYou're building an MCP server for Gmail. Here's how most developers approach it versus the agent-first design.\n\n### Before\n\nPython\n\n```python\n# Reading an email requires 2 tools + understanding nested types\ndef messages_list(query: str, max_results: int) -> {\"messages\": [{\"id\": str, \"threadId\": str}], \"nextPageToken\": str}: ...\ndef messages_get(message_id: str, format: str) -> {\"id\": str, \"snippet\": str, \"payload\": {\"headers\": list, \"body\": {\"data\": str}}}: ...\n \n# Sending an email requires base64-encoding a MIME message\ndef messages_send(message: {\"raw\": str}) -> {\"id\": str, \"threadId\": str}: ... # raw = base64url RFC 2822\n \n# Creating a draft has nested message object\ndef drafts_create(draft: {\"message\": {\"raw\": str}}) -> {\"id\": str, \"message\": {\"id\": str}}: ...\n```\n\n**Problems:** Agent must construct `{\"raw\": base64(...)}` and parse nested `payload.body.data`. Generic names.\n\n### After\n\nPython\n\n```python\n# Reading: 2 flat tools with curated returns\ndef gmail_search(query: str, limit: int = 10) -> [{\"id\": str, \"subject\": str, \"sender\": str, \"date\": str, \"snippet\": str}]: ...\ndef gmail_read(message_id: str) -> {\"subject\": str, \"sender\": str, \"body\": str, \"attachments\": [str]}: ...\n \n# Writing: Simple examples, not including cc, bcc.\ndef gmail_send(to: List[str], subject: str, body: str, reply_to_id: str = None) -> {\"success\": bool, \"message_id\": str}: ...\n```\n\n## Skills vs. MCP: Complementary, Not Competitive\n\nSkills package instructions, metadata, and resources that the agent uses when relevant. They're filesystem-based with progressive disclosure. Each skill has a name, description, which is part of the Model context. The Model/Agent can then decide to use the skill or not based on the given context.\n\n| Level | When Loaded | Token Cost | Content |\n| ---------------- | -------------- | ------------ | ---------------------------------- |\n| **Metadata** | Startup | \\~100 tokens | `name` and `description` from YAML |\n| **Instructions** | When triggered | <5k tokens | SKILL.md body |\n| **Resources** | As needed | Unlimited | Scripts via bash |\n\nSkills don't add tool definitions directly, but can include scripts that run locally to provide capabilities similar to MCP servers. The difference is that skills leverage generic execution tools (like `bash`) rather than defining new tool schemas. Leading to potentially more steps and discovery needed. MCP provides a structured interfaces. The model gets parameter validation, typed responses.\n\nNeither is better than the other. It depends on the use case and your preference. In company contexts, MCP servers shine when teams expose their own services. Skills complement this by teaching agents when and how to combine those tools for specific workflows. Use both.\n\n## Conclusion\n\nWhen building an MCP Server you are not building infrastructure, you are building an interface for AI agents.\n\n1. **Outcomes over operations:** Design for agent goals\n2. **Flatten arguments:** Primitives and enums\n3. **Instructions are context:** Docstrings and errors matter\n4. **Curate ruthlessly:** Fewer tools, tighter responses\n5. **Name for discovery:** Service-prefixed names\n6. **Paginate results:** Metadata for large lists\n\nMCP is a User Interface for AI agents. Build it like one.\n\n*Other resources: [Block's MCP Playbook](https://block.xyz/inside/designing-high-quality-mcp-servers), [GitHub's Security Guide](https://github.blog/ai-and-ml/generative-ai/how-to-build-secure-and-scalable-remote-mcp-servers/), [FastMCP AI Engineering Summit](https://www.youtube.com/watch?v=96G7FLab8xc).*\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "dateCreated": "2026-09-27T19:29:15.293681927+00:00", "date_created": "2026-01-21T00:00:00+00:00", "date_modified": "2026-01-21T00:00:00+00:00", "date_published": "2026-01-21T00:00:00+00:00", "description": "The Model Context Protocol (MCP) has exploded roughly 1 year ago, everyone rushed to build MCP servers. The hype was real. Yet, most MCP servers disappoint. Most developers blame the protocol. The protocol feels like it's dying on social…", "external_url": "https://www.philschmid.de/mcp-best-practices", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/philschmid-de/2026/01/2026-01-21-mcp-is-not-the-problem-it-s-your-server-best-practices-for.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/philschmid-de/2026/01/2026-01-21-mcp-is-not-the-problem-it-s-your-server-best-practices-for.md" }, "id": "urn:aggr:item:a568ca25112cea344749b623ea79d29b49a508df", "isBasedOn": { "@id": "https://www.philschmid.de/mcp-best-practices" }, "mainEntity": { "@id": "https://www.philschmid.de/mcp-best-practices", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-01-21-mcp-is-not-the-problem-it-s-your-server-best-practices-for/#webpage" }, "dateModified": "2026-01-21T00:00:00+00:00", "datePublished": "2026-01-21T00:00:00+00:00", "headline": "MCP is Not the Problem, It's your Server: Best Practices for Building MCP Servers", "timeRequired": "PT6M", "url": "https://www.philschmid.de/mcp-best-practices", "wordCount": 1325 }, "name": "Archived snapshot: MCP is Not the Problem, It's your Server: Best Practices for Building MCP Servers", "preview": null, "reading_minutes": 6, "replicated_at": null, "source": "philschmid-de", "source_name": "philschmid.de - RSS feed", "summary": "The Model Context Protocol (MCP) has exploded roughly 1 year ago, everyone rushed to build MCP servers. The hype was real. Yet, most MCP servers disappoint. Most developers blame the protocol. The protocol feels like it's dying on social media.", "tags": [], "temporalCoverage": "2026-09-27T19:29:15.293681927+00:00", "title": "MCP is Not the Problem, It's your Server: Best Practices for Building MCP Servers", "url": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-01-21-mcp-is-not-the-problem-it-s-your-server-best-practices-for/", "word_count": 1325 }