MCP tips, tricks and pitfalls from the field

The tips below come straight from the sources that matter in 2026: the official MCP documentation, Anthropic's engineering guidelines for tool design, and documented incidents such as the postmark-mcp backdoor. New to the basics? Start with what MCP is and how MCP works.

How do you choose a good MCP server? Tips for users

1. Choose servers with a verified namespace

The official MCP registry (registry.modelcontextprotocol.io) ties server names to proven ownership: only someone who demonstrably owns a GitHub account or domain may publish under io.github.username/... or com.company/.... That is the strongest trust signal in the ecosystem: com.stripe/... really is Stripe, io.github.random-user/stripe-mcp is not. As of March 2026 the official registry counts around 3,000 servers — deliberately much smaller than scraped directories such as mcp.so with 23,000+ listings, precisely because publishing requires verification. So start with the vendor's own first-party server and check the namespace. For more on assessing sources, see trusted sources.

2. Check whether the server is maintained

A listing in a directory is a place to find servers, not a seal of approval — even the official registry literally states in its moderation policy that users should assume "minimal-to-no moderation": servers with known vulnerabilities are not removed from it. So look for maintenance signals yourself: recent commits and releases, answered issues, a changelog, and version numbers that match across the registry, npm and GitHub. A server that hasn't been updated since 2025 is almost certainly targeting outdated spec revisions. And be careful using GitHub stars as an argument: popularity is not safety — according to Snyk, the malicious postmark-mcp package had around 1,500 downloads by the time it was caught.

3. Start read-only and with minimal permissions

Never give an agent more access than the task requires. The Supabase incident of July 2025 is the textbook example: an agent ran with the service_role key that bypasses all Row-Level Security, and a single prompt injection in a support ticket was enough to leak an entire table of tokens. Virtually every serious server now offers a read-only mode or scoped keys — use them, especially in the first weeks. Only expand permissions when a concrete task demonstrably requires it. Why this matters so much, including Simon Willison's "lethal trifecta" model, is covered on our security page.

4. Fewer servers is better

Every active MCP server loads all of its tool descriptions into the model's context window — before your first question is even asked. Ten servers with twenty tools each means hundreds of descriptions the model has to weigh on every turn. The result: the model picks the wrong tool more often, responses get slower and more expensive, and the context is polluted before the real work begins. The rule of thumb: enable only the servers you need for the task at hand, and switch the rest off. One well-chosen server beats ten half-relevant ones.

5. Know your client's tool limits

MCP clients handle large numbers of tools differently: some truncate the list, others load everything and let the model drown. A server with thirty tools can therefore work fine in one client and become unreliable in another — Towards Data Science describes how such a server confuses the model and eats up the context window before the conversation even starts. Before rolling out, check how many tools your clients can handle and how they behave at the limit. In "Code execution with MCP", Anthropic also points out that agents can handle large toolsets more cheaply by writing code against the tools instead of calling each tool individually.

How do you build a good MCP server? Tips for builders

6. Build a few good tools, not an API mirror

The biggest design mistake is mirroring your REST API one-to-one into tools. Anthropic's engineering guideline "Writing effective tools for agents" is explicit: build "a few thoughtful tools targeting specific high-impact workflows". So not list_users + list_events + create_event as three separate tools, but one schedule_event that handles the entire workflow. A tool is a user interface for an agent, not an API wrapper. Consolidate around goals the agent actually has, use namespacing per service (jira_search, asana_projects_search) and unambiguous parameter names such as user_id instead of user.

7. Write descriptions as if onboarding a new colleague

The model chooses tools based on their descriptions, not on the code behind them. In practice, a vague description means the tool never gets called — or gets called at the wrong moment. Anthropic's rule of thumb: describe your tool the way you would explain it to a new hire — make implicit context explicit, spell out parameter formats ("two-letter state code, e.g. CA") and what the tool returns. According to the same engineering post, small refinements to descriptions deliver "dramatic" accuracy gains. It is the cheapest optimisation there is: you rewrite one docstring and the behaviour of every agent using your server improves.

8. Return error messages the agent can act on

An agent that gets back "Error 422" starts guessing; an agent that gets back "state must be a two-letter code such as CA or NY" corrects itself in a single turn. So never return bare error codes or stack traces, but actionable instructions that explain what went wrong and how to do it right. The same applies to successful responses: return semantically meaningful fields and leave out internal UUIDs and technical URLs — they cost tokens and don't help the model. Consider a response_format parameter (concise/detailed) so the agent can decide how much detail a task requires.

9. Paginate everything that can grow large

A tool that dumps thousands of rows into a single response blows up the context window and makes every subsequent step worse. Implement pagination, filtering and truncation with sensible defaults — and when truncating, explicitly tell the model how to fetch more, so it learns to work with many small, targeted queries instead of one mega-query. Test this with realistic data: most pagination bugs only appear at production volumes, not with the three test records from your development environment. Anthropic names token efficiency a core criterion of tool design and recommends reading back transcripts of agent sessions to see where responses go off the rails.

10. Use absolute paths in the client config

The most mundane yet persistent mistake from the official quickstart documentation: relative paths in claude_desktop_config.json. The client launches your server as a child process from a different working directory than you expect — so always use the absolute path to your project and, where needed, to the executable itself (which uv tells you where uv lives). On Windows: double backslashes. And restart Claude Desktop after every configuration change, otherwise the new config simply won't be loaded. The complete step-by-step guide from code to working connection is at build an MCP server.

11. Test with the MCP Inspector first, then with a client

Debugging via Claude Desktop means: edit the config, restart, wait, read the log file — an agonisingly slow cycle. The official MCP Inspector (npx @modelcontextprotocol/inspector) gives you, without any installation, a web UI in which you can call tools with arbitrary arguments, inspect resources and watch the raw JSON-RPC messages live. Launch it directly against your server (npx @modelcontextprotocol/inspector uv run server.py) and verify that every tool does what its description promises, before you configure even a single client. If things still break later in Claude Desktop, check ~/Library/Logs/Claude/mcp*.log; in Claude Code, /mcp shows the server status.

Which pitfalls come up most often in practice?

12. Logging to stdout on stdio servers

According to the official MCP documentation, this is the number one cause of "my server won't start": with the stdio transport, all JSON-RPC communication runs over stdout, so one stray print() or console.log() corrupts the message stream and the server goes silent — without a clear error message. The fix is simple: log to stderr (print(..., file=sys.stderr) in Python, console.error() in Node) or to a file. Watch out for hidden culprits: a library that writes to stdout on import will also break your server. HTTP servers don't have this problem — there, stdout logging is perfectly safe.

13. Building new servers on SSE

The old HTTP+SSE transport with two endpoints has been deprecated since spec version 2025-03-26, but still circulates widely in tutorials and example code. Anyone building on it today is building on a dead end: Atlassian, for example, only kept its old /v1/sse endpoint alive until 30 June 2026. The rule of thumb for 2026: stdio for local and personal use, Streamable HTTP as soon as anything needs to be remote, shared or hosted — SSE never again for new builds. Streamable HTTP uses a single endpoint (usually /mcp) and aligns with the stateless direction of the spec release of 28 July 2026.

14. Following outdated tutorials from before 2025

The MCP ecosystem moves fast and old content ages just as fast. Tutorials from before 2025 teach you SSE transports (deprecated), point to reference servers that have since been moved to modelcontextprotocol/servers-archived and are no longer maintained, and miss everything around OAuth 2.1 and the official registry. Even more recent guides may rely on features being phased out with the spec of 28 July 2026: Roots, Sampling and Logging are deprecated with a twelve-month transition window. Check the publication date of every tutorial and test its content against the official documentation at modelcontextprotocol.io — see also our sources page.

15. Accepting or granting overly broad OAuth scopes

The official MCP specification devotes an entire section to scope minimisation and names the classic mistakes: wildcard scopes such as db:* or admin:*, bundling unrelated permissions "to avoid future prompts", and publishing every conceivable scope in scopes_supported. Every overly broad scope amplifies the damage when — not if — a token leaks, and causes consent fatigue: users blindly click through long permission lists. The alternative is progressive least privilege: start with a minimal base scope and request additional permissions only at the moment a privileged operation is actually performed. For the legal side of data access, see MCP and EU regulation.

16. Installing phantom servers and typosquats from registries

According to the 2026 UpGuard study, which analysed 18,000 Claude Code configurations and four registries, 10 to 16 percent of all MCP servers in the registries examined are typosquats or lookalikes — with 3 to 15 unverified imitations per official brand name. Of the nine "HubSpot" servers found, exactly one was genuine. A single miscopied character (mcp-server-sqllite instead of mcp-server-sqlite) installs attacker code that runs on every agent start. So copy installation commands exclusively from the vendor's own official documentation or repository, and verify the publisher namespace before installing.

Further reading

Last updated: 2026-07-06