An MCP server is a program that exposes tools, data, and prompts to AI applications through the Model Context Protocol (MCP), an open standard for connecting AI models to external systems. You build an MCP server by defining tools with an official SDK, and you use one by adding its URL or launch command to an MCP client such as Claude or Cursor.
This guide follows the 2026-07-28 MCP specification, which changed how MCP servers are built. Many older tutorials describe a flow that no longer applies. Most clients still speak the older flow too, and this guide says where that matters.
Key takeaways
- An MCP server wraps an external system, such as an issue tracker or a database, so that any MCP-compatible AI application can discover and call its capabilities.
- Tools are the part of an MCP server that matters most. Resources and prompts exist in the specification but see little real-world use.
- Since the 2026-07-28 specification, MCP servers are stateless: there is no handshake and no session ID, and every request carries its own context. Most clients still send the old handshake, so a server should answer both.
- The quality of an MCP server depends mostly on its tool descriptions. One benchmark of 41,902 MCP servers gave an A grade to only 0.5% of them.
- An MCP server is the wrong choice for a coding agent that already has a terminal and a well-known CLI. It is the right choice when the agent has no shell or must never see credentials.
- The servers with real traffic get most of it from coding agents and products, not chat windows. PostHog measured 7% of 63 million tool calls coming from a chat.
What is an MCP server?
An MCP server is a program that gives AI applications access to an external system through the Model Context Protocol. The MCP server wraps a service such as GitHub, a database, or an internal tool, and describes what it can do so that an AI model can discover and call those capabilities without custom integration code.
For example, an MCP server for an issue tracker lets a model list, create, and update issues. When a user asks "what is blocking the release?", the model calls the server's search tool and answers from live data.
MCP was introduced by Anthropic in November 2024 and is now an open standard hosted as a Linux Foundation project. The official SDKs see close to half a billion downloads a month, according to the MCP maintainers' July 2026 release post.
How does an MCP server work?
An MCP server works by answering two kinds of request from an AI application: "what tools do you have?" and "run this tool with these arguments." The application shows the tool list to the model, the model picks a tool, and the MCP server executes it and returns the result for the model to use.
| Part | What it is | Example |
|---|---|---|
| Host | The AI application the person uses | Claude, Cursor, a custom support agent |
| Client | The connector inside the host that speaks MCP | One client per connected server |
| MCP server | The program that wraps an external system | A server for GitHub, Postgres, or an internal billing system |
| Tool | A function the model can call | find_overdue_invoices(customer_name) |
| Resource | Read-only data the host can attach as context | A file or a database schema |
| Prompt | A reusable prompt template the user can invoke | A "summarize this incident" template |
Tools are the part of an MCP server worth learning first. Simon Willison, co-creator of Django and a prominent writer on LLM tooling, estimated in September 2026 that tools account for more than 95% of what people use MCP for. A GitHub code search by Tom Bedor in December 2025 found the same ratio in the wild: about 58,100 uses of @mcp.tool against 9,100 of @mcp.resource and 6,100 of @mcp.prompt.
What the messages look like
Strip the SDK away and an MCP server reads one JSON object per line and writes one back. The format is JSON-RPC 2.0. Here is a complete session with a one-tool server, captured from a real run by Oluwatosin Aramide on the 2025-11-25 revision:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"wire-demo","version":"1.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"subnet_info","arguments":{"cidr":"10.110.0.0/24"}}}
Line 2 is a notification. It has no id and gets no reply. Every request with an id gets exactly one response. The reply to the tool call is a list of content blocks plus an error flag:
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"cidr\": \"10.110.0.0/24\", \"network\": \"10.110.0.0\", ...}"}],"isError":false}}
That is the whole protocol for a tool-only server: four handlers. One developer wrote one in Zig with no SDK. His note: "most of the hard work has already been done in the JSON-RPC library." You can test any stdio server from a shell by piping one of these lines into it.
Since the 2026-07-28 specification, the first two lines go away. Each request is a self-contained HTTP POST. The method and tool name are repeated in headers so a load balancer can route or rate-limit without parsing the body, and the client identity that used to live in the handshake rides along in _meta. This example is from Rupa Tiwari's migration write-up:
POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Method: tools/call
Mcp-Name: get_user
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
"name":"get_user",
"arguments":{"id":"123"},
"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientInfo":{"name":"my-client","version":"1.0.0"}
}
}}
A new method, server/discover, replaces initialize. Every list response now carries ttlMs and cacheScope, so a client can cache the tool list and a CDN can serve it. A quick way to tell which era a remote server is on: send a tools/list with the Mcp-Method header. A response with ttlMs in it is a new server. Error code -32022 is an old one.
If a tool needs to ask the user something mid-call, there is no session to park the question in. The server returns resultType: "input_required" with a signed requestState blob. The client collects the answer and retries the same call with the blob attached. The state lives in the request, not on the server.
Where the ecosystem really is
The specification is stateless. Almost nothing you connect to in October 2026 speaks it yet.
Claude Code tries server/discover by default and falls back to initialize. Codex ships the new version behind a flag that is off. Cursor, VS Code, and Gemini CLI are on 2025 revisions. The MCP Transparency Log, an independent nightly census of the official registry, found 6,716 reachable servers negotiating the 2025-06-18 revision in late August 2026 and 17 on 2026-07-28. A probe of 500 registry servers in October found one that had dropped the old handshake.
So a server you build today should answer both. The hosted servers that migrated early, such as Sentry's, kept the old path alive alongside the new one.
Why it looks like this
MCP borrowed its shape from the Language Server Protocol: one wire format, many editors, many languages. Its creators, Justin Spahr-Summers and David Soria Parra, started it in mid-2024 after an internal LSP project at Anthropic went nowhere. The first IDE client was Zed, written about six weeks before launch.
They picked JSON-RPC because, in Spahr-Summers' words, "it doesn't matter at all." The work was meant to be in the primitives, not the encoding. They also pushed complexity to the client on purpose, because "we expect that there's way fewer clients than servers."
The one decision they defended hardest was state. They expected AI sessions to become "inherently more stateful" and designed long-lived connections. Operators fought that for twenty months. Sessions tied a client to one replica, broke on deploys, and needed Redis to scale. When the 2026-07-28 revision removed them, one gateway maintainer wrote that "sessions were not a detail in that design. They were the spine." A commenter on the roadmap thread was blunter: "The real disaster was making it stateful."
What is the difference between an MCP server and an API?
An API is called by code a developer wrote in advance, while an MCP server is called by an AI model that decides at runtime which capability to use. An MCP server usually sits on top of an existing API and adds what a model needs: discoverable tool names, plain-language descriptions, and typed inputs.
| Criterion | MCP server | REST API |
|---|---|---|
| Who decides what to call | The AI model, at runtime | A developer, at build time |
| How capabilities are discovered | The server lists its tools with descriptions and schemas | A person reads the documentation |
| Shape of each operation | A task, such as "find overdue invoices" | A resource endpoint, such as GET /invoices |
| Where credentials live | In the client or server, outside the model's reach | In the calling code |
| Best for | Letting many AI applications use one system | Application-to-application integration |
An MCP server does not replace an API. The MCP server is the layer that makes an API usable by a model that has never seen its documentation. The creators put it the same way: OpenAPI specs are "too granular for what you want to do with LLMs," and the two are complementary.
MCP server vs CLI vs skills vs code mode
REST is the wrong comparison for most developers in 2026. The live question is MCP against the three other ways to give an agent a capability: a command-line tool, a skill file, and code mode.
| Option | What it is | Where it wins | Where it loses |
|---|---|---|---|
| CLI | A binary the agent runs in a shell | Famous tools (git, gh, aws), pipes, near-zero token cost | Needs a shell; credentials sit in the agent's environment; no per-tool permission by name |
| Skill | A Markdown file of instructions the agent reads | Workflows and judgment the model lacks | Cannot sign you in to anything or set anything up |
| MCP server | Typed tools behind a protocol any host speaks | Non-terminal hosts, OAuth per user, central revocation, audit logs | Tool definitions cost context; one call per model turn |
| Code mode | The model writes a script that calls many MCP tools at once | Multi-step tasks over large APIs | Needs a sandbox; adds a layer to debug |
The fairest test so far is Arize's benchmark from May 2026: one model, 25 GitHub tasks, 500 trials across GitHub's MCP server, two skill files, and a bare shell. Correctness was a wash. Every option scored between 0.83 and 0.85. Cost was not. On the hardest tasks the MCP server cost over six times the skills and took five times longer, because it averaged 12 tool calls where the skills needed 5. But when a task mapped to one endpoint, MCP won: creating a branch and a pull request took 33 seconds via MCP and about 90 seconds via the long skill.
The author's two conclusions hold up across every thread on the topic. "The shape of the task determines the winner." And: "Your company's CLI is not as famous as GitHub's." The CLI wins for tools the model already knows. For your internal billing system, it knows nothing, and a tool description is how it learns.
Code mode is the newer idea. Instead of one tool call per turn, the model writes a short program that calls several tools and returns only the result. In one vendor's test of 12 Stripe tasks, all three approaches got 12 of 12 right, but code mode used 295,000 tokens to raw MCP's 507,000 and the CLI's 712,000. Code mode is how MCP tools get used. It does not replace how they get found and governed.
Two other protocols come up and are neither rivals nor replacements. A2A is agent-to-agent, for tasks that can run for days. ACP, from Zed, is editor-to-agent. An agent is an ACP server to its editor and an MCP client to its tools.
Why are MCP servers useful?
MCP servers are useful because one server makes a system available to every MCP-compatible AI application, with no separate integration per model or vendor. An MCP server also keeps credentials away from the model, gives administrators one place to control access, and lets non-developers connect a service by pasting a URL.
- Build once, connect anywhere. One MCP server works with any host that speaks MCP, instead of a custom plugin for each AI product.
- Credentials stay out of the model's reach. The MCP server holds the API keys or handles sign-in, so a manipulated model cannot read or leak them.
- Access is controllable and auditable. An MCP server exposes only the operations its owner chose, and every tool call can be logged.
- Setup takes one step for the end user. Adding a remote MCP server means entering a URL and signing in, with nothing to install.
Simon Willison gave the same four reasons in a September 2026 comment: control over which services an agent can reach, authentication that hides API keys from the agent, a usable interface for connecting services, and audit logging.
One more reason shows up in nearly every Hacker News thread from someone who did not want to build a server and did anyway. Their agent-friendly API worked fine from a terminal, but hosted agents cannot make arbitrary outbound requests. One founder put it plainly: "It does not work on chatgpt.com because the sandbox does not allow arbitrary outbound web requests." The MCP server was the only door in.
What the traffic looks like
The servers with real volume are not chat toys.
PostHog's server took 63 million tool calls in 90 days from about 130,000 people. Only 7% of calls came from a chat window. Among third-party clients, Claude Code sent 32%, Codex 22%, and Cursor 10%. Claude Desktop, Claude.ai, and ChatGPT sent 2% to 3% each. One tool, execute-sql, took a quarter of all calls. Agents created 252,000 insights through the server in that period. Humans created 99,000 in the web app.
Sentry's server handles about 60 million requests a month across more than 5,000 organizations. Three people run it. Cloudflare's server for its own API has handled billions of tool calls.
PostHog's write-up has one line worth keeping in mind for the rest of this guide: "The agent poking at your product almost certainly isn't in a chat window."
What people actually connect
From Hacker News threads and the Pragmatic Engineer survey of 46 engineers, the servers that come up again and again fall into a few classes.
- Trackers and docs with no CLI: Linear, Jira, Notion, Slack. The draw is OAuth for individuals. One commenter on Atlassian's server: you can sign in yourself "where before you needed to request API keys via your org, which is something no admin would approve."
- Error monitoring: Sentry. A principal engineer in the survey hands Cursor a Sentry issue link and asks for a fix plan.
- Design to code: Figma. Razorpay's open-source design-system server was used by 70% of their frontend engineers to build features without writing code by hand.
- Browser eyes: Playwright and Chrome DevTools. The most cited servers, and the most often replaced by a CLI because of token cost.
- Internal data: Jeremiah Lowin, who wrote FastMCP, says "almost every team that we talk to now is an internal team serving internal stakeholders." Stainless runs an OAuth proxy in front of a read replica. Non-technical staff query it with one button.
- Home and personal: Home Assistant behind a Cloudflare tunnel into Claude on the web, Obsidian notes, Garmin data synced into a personal database.
One cautionary tale belongs here. A SnapTrade engineer built a trading server with a place_order tool. After a failed trade, the model "kept retrying with larger quantities on its own."
When should you not build an MCP server?
You should not build an MCP server when the agent already has a terminal and a well-known command-line tool for the job, or when the task is a fixed workflow that a script could run. An MCP server earns its cost only when the agent has no shell, must never see credentials, or serves non-developers.
| Situation | Better choice | Why |
|---|---|---|
| A coding agent with a terminal, and a mature CLI exists (git, gh, aws) | The CLI | The model already knows the CLI and loads no tool definitions up front |
| The same steps run the same way every time | A script | A fixed workflow needs no model in the loop |
| A chat or support agent with no shell | MCP server | Tools are the only way the agent can act |
| The agent must not be able to read API keys | MCP server | Credentials stay inside the server |
| Non-developers connect their own accounts | Remote MCP server | A URL and a sign-in, with nothing to install |
| Many teams or products need the same system | MCP server | One integration serves every MCP host |
The token cost behind the first row is measured. Scalekit's benchmark of 75 runs found that GitHub's MCP server, which loads 43 tool definitions, used 4 to 32 times more tokens than the gh CLI on the same tasks. Arize's larger test, covered above, found the same cost gap with no difference in correctness.
The people who switched away wrote down their numbers. Josh Owens deleted seven servers after his context showed "67,300 tokens. Gone before I said hello." He swapped Playwright's 21 tools, about 13,600 tokens, for a browser CLI and a skill at about 2,000. He kept MCP for "products that constantly need access to a specific service, such as a customer support bot." That is the same line everyone who switched draws: terminal work goes to the CLI, products and non-terminal hosts stay on MCP.
That benchmark measures one implementation choice, not a limit of MCP. An MCP server with five well-described tools, or a host that loads tool definitions on demand, avoids most of that overhead. Tool definitions load on every request, which makes them one of the silent token drains in an agent session.
How do you build an MCP server?
You build an MCP server in four moves: choose the few tasks it should perform, define each task as a typed function with an official SDK, test it in the MCP Inspector, and run it locally over stdio or remotely over Streamable HTTP. A working single-tool MCP server takes about 25 lines of Python.
- Choose three to five tasks. List what a user would ask for, such as "find overdue invoices", and make each one a tool. Do not mirror every API endpoint.
- Install an official SDK. TypeScript, Python, Go, and C# are the Tier 1 SDKs for the 2026-07-28 specification. For Python, run
uv add "mcp[cli]". - Define each tool as a typed function. The SDK turns the function name, type hints, and docstring into the tool definition the model reads.
- Test the server in the MCP Inspector. Run
uv run mcp dev server.py, call each tool by hand, and check the output. - Pick a transport. Use stdio when the MCP server runs on the user's machine. Use Streamable HTTP when it runs as a hosted service:
uv run mcp run server.py --transport streamable-http. - Add authorization to a remote server. Remote MCP servers use OAuth. The current specification favors Client ID Metadata Documents over Dynamic Client Registration.
- Keep state explicit. If a tool needs to continue earlier work, return a handle, such as a
report_id, and accept it as an argument on the next call. - Answer both protocol generations. Keep
initializeworking next toserver/discoverfor at least a year. Most clients still send the old handshake.
This complete MCP server follows the pattern in the official Python SDK. It was run against SDK version 2.2.0 on October 1, 2026.
from mcp.server import MCPServer
mcp = MCPServer("Invoices")
INVOICES = [
{"id": "INV-1042", "customer": "Acme Corp", "amount_usd": 1800.0, "days_overdue": 45},
{"id": "INV-1077", "customer": "Acme Corp", "amount_usd": 320.0, "days_overdue": 12},
]
@mcp.tool()
def find_overdue_invoices(customer_name: str, min_days_overdue: int = 30) -> list[dict]:
"""Find unpaid invoices for one customer that are past their due date.
Use this when someone asks what a customer owes or which invoices are late.
Returns a list of invoices with id, amount_usd, and days_overdue, or an
empty list if nothing is overdue. customer_name is the company name as it
appears in billing, for example "Acme Corp".
"""
return [
i for i in INVOICES
if i["customer"].lower() == customer_name.lower()
and i["days_overdue"] >= min_days_overdue
]
Called with customer_name="acme corp", this MCP server returns invoice INV-1042 only, because the second invoice is 12 days overdue and the default threshold is 30. The full tool definition the model receives is 914 characters of JSON.
Three habits from teams running servers at scale are worth adopting from day one.
- Return Markdown, not JSON. Notion reversed a 2022 API decision and now returns Markdown instead of block JSON, because "Markdown provides efficient content density per LLM token." Sentry landed in the same place. PostHog's server returns about 30 tokens for every token it receives, and most of that is output you pay for on every turn.
- Serve a web page on the MCP URL. Users will open your server's address in a browser and see a raw 401. One operator returns an HTML explainer when the request accepts
text/htmland nothing else. His support tickets "dropped off a cliff." - Set the annotations honestly.
readOnlyHintanddestructiveHintare hints, not guarantees. Clients treat them differently: some auto-approve read-only tools, others ignore the flags. Set them anyway. A tool you mark read-only and then make write is the kind of thing scanners now flag.
For a longer build that hits the real edges (stdout as the wire, the wrong primitive, junk arguments, a slow upstream), see Build an MCP Server in Four Passes. Claude Code users can also lean on the mcp-builder skill from our Claude Code skills guide.
Many MCP tutorials written before July 2026 describe steps that are now retired or deprecated.
| Older tutorials say | Current practice (2026-07-28 specification) |
|---|---|
Open every connection with an initialize handshake and track Mcp-Session-Id | No handshake and no session ID; each request is self-contained. Keep initialize working for old clients |
| Keep state in the protocol session | Return an explicit handle from a tool and pass it back as an argument |
| Use the HTTP+SSE transport for remote servers | HTTP+SSE is deprecated; use Streamable HTTP |
| Register clients with Dynamic Client Registration | Deprecated in favor of Client ID Metadata Documents |
| Use Sampling, Roots, and Logging | Deprecated; still working for at least twelve months, not for new servers |
from mcp.server.fastmcp import FastMCP | Python SDK v2 uses from mcp.server import MCPServer; pip install mcp now installs 2.x |
How do you write a good MCP tool description?
A good MCP tool description tells the model four things: what the tool does, when to use it, what each parameter means, and what comes back. The model chooses tools by reading these descriptions and nothing else, so a vague description produces wrong tool choices however good the code behind it is.
Most published MCP servers fail this test.
- Arcade's ToolBench (2026) graded 41,902 MCP servers and 218,422 tools. Only 0.5% of servers earned an A, and 167,333 tools received an F. Missing descriptions were the most common problem.
- A 2026 study of 10,831 MCP servers found description flaws were pervasive and called the pattern "code-first, description-last."
- Research summarized in a 2025 empirical paper found that 97.1% of 856 tools had at least one description flaw and 56% did not state their purpose clearly.
The same tool, described two ways:
| Weak | Strong | |
|---|---|---|
| Name | get_data | find_overdue_invoices |
| Description | "Gets data." | "Find unpaid invoices for one customer that are past their due date. Use this when someone asks what a customer owes or which invoices are late." |
| Parameters | id: str | customer_name: str, the company name as it appears in billing, for example "Acme Corp" |
| Return value | Not stated | "A list of invoices with id, amount_usd, and days_overdue, or an empty list if nothing is overdue." |
Three things the benchmarks do not tell you.
Clients cut long descriptions. Claude Code truncates a tool description at 4,096 characters when loaded up front, and at 16,384 when loaded through tool search. A description longer than that is not read. It is cut.
Fold variants into one tool. Scott Spence cut his own server from 20 tools and 14,214 tokens to 8 tools and 5,663 by giving near-duplicate tools a single provider or mode parameter. One description went from 87 tokens to 12.
Say what to call next. Sentry's descriptions include a concrete example call and the next step, such as "call list_organization first." The model reads the description before it calls anything, so that is where the routing advice belongs.
A checklist for every tool on an MCP server:
- The name is a verb plus a specific object.
- The first sentence states the purpose.
- One sentence says when to use the tool.
- Every parameter has a meaning and an example value.
- The return value is described, including the empty case.
- The description says what to call before or after, if there is an order.
- Error messages tell the model what to do next, such as "customer not found; try search_customers first."
How do you connect and use an MCP server?
You connect an MCP server by adding it to an MCP client: paste the URL of a remote server into the client's connector settings and sign in, or add the launch command of a local server to the client's configuration. After that, you ask for what you want in plain language and the model calls the tools.
The config file is the easy part. The traps are where the file lives, how many tools your client will accept, and what happens when the server fails to start.
Where each client keeps its config
| Client | Config file | Key | What trips people up |
|---|---|---|---|
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\ (Windows) | mcpServers | Read once at startup. Quit the app fully, closing the window is not enough. Remote servers are added as Connectors in Settings, not in the file |
| Claude Code | ~/.claude.json for user scope, .mcp.json in the project for project scope | mcpServers | claude mcp add defaults to local scope, so the server vanishes in another directory. Use --scope project or --scope user |
| Cursor | ~/.cursor/mcp.json or .cursor/mcp.json | mcpServers | Sends the first 40 tools across all servers and silently drops the rest, per 2025 reports |
| VS Code | profile mcp.json or .vscode/mcp.json | servers, not mcpServers | Caps a request at 128 tools, then groups them into "virtual tools" |
| Codex CLI | ~/.codex/config.toml | [mcp_servers.<name>] | Must be an underscore. mcpServers is ignored with no error. Startup timeout is 10 seconds |
| Gemini CLI | ~/.gemini/settings.json or .gemini/settings.json | mcpServers | url means the old SSE transport. Use httpUrl for Streamable HTTP. Defaults to project scope |
| Zed | settings.json | context_servers | Leave out the Authorization header and Zed starts the OAuth flow for you |
ChatGPT has no file. Remote servers go in under Settings, Connectors, Advanced, Developer mode.
The tool caps bite sooner than you expect. One Cursor user hit the 40-tool limit with Sentry, Shortcut, and Playwright alone. Another: "I only have four mcp server, but Upstash ate the quota of tools."
The npx startup tax
Most local servers are configured as npx -y some-package@latest. That means a registry check and a possible download on every launch. Clients enforce a handshake deadline, and once a server misses it, the client marks it failed for the session and most do not retry.
One developer measured it: npx -y @azure-devops/mcp averaged 15.4 seconds on a cold start against 3.2 seconds for node dist/index.js. A Copilot CLI user saw 22 of 76 handshakes in one day blow a 60-second budget. Ben Swift traced a 30-second agent startup in Zed to the Playwright server's npx line. The same config took 5 seconds in a terminal, because "IDEs and MCP servers don't get the benefits of your shell's interactive setup automatically."
Install the package once, pin the version, and point command at the binary. If you must use npx, raise the timeout: MCP_TIMEOUT in Claude Code, startup_timeout_sec in Codex.
When a server silently fails
- Claude Desktop writes
~/Library/Logs/Claude/mcp.logplus onemcp-server-<name>.logper server. Anything the server printed to stderr is there. - Claude Code:
claude mcp listshows health,/mcpshows status and runs OAuth, and/contextshows what each tool costs in tokens. Tools with names over 128 characters or invalid JSON Schema are dropped and the model is told why. - Codex historically silenced server errors. A misnamed table, an untrusted project directory, or a TOML error elsewhere in the file all make a server vanish with no message. Check
~/.codex/log/codex-tui.log. - stdio servers inherit only a few environment variables and may start with an undefined working directory. Use absolute paths.
- Windows splits
C:\Program Files\nodejs\npx.cmdat the space. Use the short formC:\PROGRA~1\nodejs\npx.cmdor callnodewith a path. - Tool output is its own problem. Claude Code warns above 10,000 tokens of output and truncates at 25,000. A Playwright page snapshot runs about 10,800 tokens. One commenter routes every MCP call through a subagent "because they are so wordy."
If the server connects in the MCP Inspector but not in your app, the problem is the spawn layer, not the server: npx, PATH, or the timeout.
Remote servers and sign-in
Every major client now runs the browser OAuth flow. Claude Code: claude mcp add --transport http <name> <url>, then /mcp. Codex: codex mcp login <name>. Gemini: /mcp auth <name>. Each client implements a different slice of the spec, so a server that works in one may fail in another. The ChatGPT Developer Mode launch thread is a good record of the failure modes: a server that worked in Claude returning "Error fetching OAuth configuration," a registration response in the wrong shape, a 401 on token exchange.
Local servers only reach the clients that can spawn a process: Claude Code, Codex CLI, VS Code, Cursor, and Gemini CLI. Claude.ai, Claude Desktop connectors, and the Claude API need a public URL. ChatGPT reaches a local server only through its tunnel.
Too many tools
Models start confusing similar tools somewhere between 10 and 20. One Claude user complained: "it tries to connect to a GitHub repo or write to a local file even when I specify I don't want those things." Scott Spence's /context with 12 servers on: 81,986 tokens, 41% of the window, 12,000 tokens free. With one server on: 5,700 used, 88,000 free.
Three fixes, in order of effort: name the server in your prompt, switch off servers you are not using, and split servers by workflow instead of by API. Claude Code and Gemini prefix tool names with the server name, so two servers with a search tool do not collide there.
How do you vet an MCP server before installing it?
Vet an MCP server the way you would vet a browser extension with access to your accounts: confirm who publishes it, check that it is maintained, read its tool list, and grant the narrowest permissions that work. Anyone can publish an MCP server, and a connected server acts with your credentials.
The ecosystem data supports the caution. A measurement study of the MCP ecosystem found that 21.9% of servers had seen no update in more than a year. A study of 10,240 servers found about 13% had tool descriptions that only partly matched what the code did. And tools that modify external systems rose from 27% to 65% of tool usage between November 2024 and February 2026, according to a 2026 analysis of 177,436 published tools. The servers are getting more powerful and less maintained at the same time.
Here is what has gone wrong, with names.
| What can happen | A real case |
|---|---|
| A lookalike package adds a payload in a later version | postmark-mcp, September 2025. An unofficial npm package impersonating Postmark's server added a one-line BCC that copied every email to the attacker. The HN thread cites about 1,500 weekly installs |
| Tool definitions change after you approved them | Canopii's June 2026 scan of 11,524 registry servers found 184 versions whose tools changed after publication, across about 170 servers |
| The client trusts an approved config forever | Cursor, CVE-2025-54136. Approve a benign .cursor/mcp.json once, a collaborator changes the command in the shared repo, it runs on every project open. Fixed in Cursor 1.3 |
| A malicious server exploits the client during sign-in | mcp-remote, CVE-2025-6514, CVSS 9.6. A crafted authorization endpoint ran commands on the client machine. The September 2026 Python SDK flaw is the same shape |
| A local server with no auth answers anyone on the machine | Any Chrome extension can call a local SSE server, because the protocol has no origin check or token. HN thread, 148 points |
| A dev server left on 0.0.0.0 | Knostic found 1,862 servers on the public internet. Of 119 they verified, all 119 returned their tool list with no auth |
| The README says OAuth, the server does not check | A May 2026 study of 7,973 live remote servers found 40.55% expose tools with no authentication. Of 119 with testable OAuth, every one had at least one flaw |
The Canopii numbers come from a vendor that sells a gateway, and the author approves servers for an enterprise. Read them with that in mind. Two findings still stand out. Of 77 remote servers that declared auth, 24 served their full tool list to anonymous callers. And stars select for risk: servers with over 1,000 GitHub stars were 18.7% high-risk against 3.6% for servers with under 10. "Teams that whitelist 'the famous ones' are selecting for risk, not against it." A rival catalog's grading found the opposite, so treat stars as no signal either way.
The official MCP Registry does not help with any of this. Its moderation policy says it is "quite permissive" and only removes illegal content, malware, spam, and broken servers. It will not remove a server with a security vulnerability. "Verified" means the publisher owns the namespace, nothing more. One developer ran 70 registry servers under strace in throwaway containers with a canary credential. Three phoned home at boot. His summary: "the MCP registry verifies who published a server, but nothing verifies what a server does once you run it."
What people who run many servers do about it:
- Containers on a separate network. Every server in Docker on its own VLAN, and the model never connected to a main browser profile, email, or cloud account. This would not have caught postmark-mcp, since the leak happened inside a legitimate email call.
- A proxy that enforces per-tool policy. One commenter runs a proxy behind corporate OAuth with per-tool rules and says the peace of mind from "not trusting other people's slopped out MCPs" is immense.
- Read-only at the source. Give the server a read-only database account instead of a write account plus a rule. As one HN commenter put it, "agents are good at circumventing stuff ('oh, I cannot DROP table, let me just remove all rows')."
A checklist before connecting any third-party MCP server:
- The package name matches the vendor's published one exactly. One character off is the postmark-mcp pattern.
- The publisher is the vendor of the service, or a party you can identify, and the account is older than the package.
- The repository shows activity in the last 90 days, and dependencies are pinned. Stars are not evidence.
- There is no install script and no
curl | shin the setup steps. - The tool list matches what the server claims to do. Read the tool definitions, not the README.
- You saved the
tools/listoutput you approved, so you can diff it after an update. - A local server binds to 127.0.0.1 and requires a token.
- A remote server returns 401 on
tools/listwithout a token. Test it, do not read it. - You ran it once in a throwaway container with a fake credential and watched what it connected to.
- Tools that write, send, or delete require approval in your client, and the credential you gave the server is read-only wherever that is possible.
- Your client and SDK versions are current.
For teams, Enterprise-Managed Authorization went stable in June 2026. An admin enables a server for an org or group, users inherit access through the identity provider, and removing someone there removes their MCP access. It controls who can connect to which server. It does not control what the agent does once connected.
Should you run an MCP server locally or remotely?
Run an MCP server locally when it serves one person and needs files or programs on that person's machine. Run an MCP server remotely when it serves a team, customers, or any non-developer, because a remote server needs no installation and handles sign-in through OAuth.
| Criterion | Local MCP server | Remote MCP server |
|---|---|---|
| Transport | stdio | Streamable HTTP |
| Runs on | The user's machine | Hosted infrastructure |
| Setup for the user | Install and edit a configuration file | Paste a URL and sign in |
| Authentication | Keys in local environment or config | OAuth, per user |
| Access to local files and apps | Yes | No |
| Which hosts can reach it | Claude Code, Codex CLI, VS Code, Cursor, Gemini CLI | Those, plus Claude.ai, Claude Desktop, ChatGPT, the Claude API, Slack bots, mobile |
| Scaling | One user | Any instance can serve any request since the 2026-07-28 specification |
| Who answers when it breaks | You, from the client's mcp-server-<name>.log | You, from your own logs; the client does not capture stderr over HTTP |
| Best for | Personal tools, development, local data | Products, teams, non-developers |
Most new MCP servers that wrap a hosted service should be remote. The stateless core in the 2026-07-28 specification removed the session handling that used to make remote MCP servers hard to run behind a load balancer.
What "paste a URL and sign in" costs you
The user's one step is the operator's long list. One team wrote down everything it took for Claude Desktop to accept their server. A 401 with a WWW-Authenticate header pointing at resource metadata. The metadata document itself, plus authorization server metadata. A registration endpoint, because Claude had no pre-shared client ID. PKCE with S256 only, a consent screen, refresh-token rotation, and single-use auth codes. An adversarial review of their first draft found three critical bugs. One was a redirect check where startsWith('localhost') matched localhost.attacker.com.
The bug everyone hits comes after deploy. Behind a proxy, the server's idea of its own address is wrong. That team saw http://0.0.0.0:8080 as its origin, so Claude Desktop's first connection showed "This site can't be reached" and every Approve on the consent screen returned 403. Microsoft's team saw the same: the metadata advertised http://localhost:9000 after deployment. Read the public host from the forwarded headers, or configure it. Never from the request.
Going stateless made this easier, not just scaling. One operator who built stateless before the spec allowed it said the surprise was auth: "No session means no confusion about when the key was checked. Anyone can list the tools and actually calling one needs a bearer token or you get a 401."
Two more things remote operators learn fast. The server can vet the client too. Figma's remote server only grants edit access to allow-listed clients. In the HN thread about it, a security reviewer wrote: "we basically needed to do the same thing with our MCP server." And log every call with the client name, tool, token counts, and errors. Sentry shipped without telemetry and learned about outages from social media.
Frequently asked questions
Is MCP only for Claude?
No. MCP is an open standard hosted as a Linux Foundation project, and an MCP server works with any client that implements the protocol. The July 2026 specification release carried statements of support from AWS, Google Cloud, Microsoft, and Cloudflare, among others.
What languages can you build an MCP server in?
TypeScript, Python, Go, and C# have Tier 1 official SDKs that support the 2026-07-28 specification, and the Rust SDK supports it in beta. Official SDKs also exist for other languages, including PHP. Any language that can serve HTTP or read standard input can implement an MCP server without an SDK.
Which clients support the 2026-07-28 specification?
As of October 2026, Claude Code tries it by default and falls back to the old handshake. Codex has it behind a flag that is off. Cursor, VS Code, and Gemini CLI are on 2025 revisions. A server should answer both server/discover and initialize.
Is MCP free to use?
Yes. The MCP specification is open and the official SDKs are open source. The costs of an MCP server are hosting for remote servers and the model tokens consumed by tool definitions and tool results.
Do MCP servers use a lot of tokens?
It depends on the server more than the tool count. One study's estimates from tools/list output put Notion's 24 tools at about 19,000 tokens and GitHub's 26 at about 4,000. A 30x spread. GitHub's server has been measured anywhere from 4,000 to 55,000 tokens depending on the version and the tool count at the time. Claude Code defers tool definitions until a tool is used, which hides the cost at session start. Most other clients load everything. Run /context in Claude Code and disconnect what you are not using.
How many tools is too many?
Cursor sends the first 40 across all servers. VS Code caps a request at 128. Models start mixing up similar tools somewhere between 10 and 20. One MySQL server with 106 tools costs about 54,600 tokens on every session start. Split servers by workflow, not by API.
Can an MCP tool run for a long time?
The specification moved long-running calls into a tasks extension that the client polls. As of October 2026 no major client implements it. Return a handle and let the model poll your own status tool.
What is MCP Apps?
An optional extension where a tool returns an interface rendered in an iframe inside the host. Claude.ai and ChatGPT render it. Claude Code and VS Code show the text result only. The iframe holds no credentials, so everything it displays has to be passed through the conversation.
Is the MCP Registry vetted?
No. It verifies that the publisher owns the namespace and removes malware, spam, and broken servers. Its policy says it will not remove servers with security vulnerabilities.
Does MCP compete with A2A, ACP, or skills?
No. A2A is agent-to-agent, ACP is editor-to-agent, and a skill is a document the agent reads. A skill cannot sign you in to anything. An MCP server cannot teach the model a workflow. Teams ship both.
Is MCP dead?
No. Developers running coding agents with terminal access have moved some work from MCP servers to command-line tools, and that criticism is valid for that case. The traffic is elsewhere. PostHog's server took 63 million calls in a quarter with 7% from chat windows. Sentry's takes 60 million a month. The MCP maintainers reported close to half a billion SDK downloads a month in July 2026.
What changed in the 2026-07-28 MCP specification?
The 2026-07-28 MCP specification made the protocol stateless. It removed the initialize handshake and the session ID, added routing headers and cacheable tool lists, and deprecated Roots, Sampling, Logging, the HTTP+SSE transport, and Dynamic Client Registration, each with at least a twelve-month window.
Sources and methodology
This guide is based on the MCP specification and SDK documentation, published benchmarks and academic studies, and practitioner discussion on Hacker News and personal developer blogs, all as of October 21, 2026. The code sample was run against the official Python SDK, version 2.2.0. The ecosystem statistics come from the third-party studies linked below, not from our own measurement. Where a study was published by a vendor, the text says so.
- The 2026-07-28 Specification, Model Context Protocol blog, July 28, 2026
- MCP Python SDK, official repository
- Simon Willison's comment on "MCP was always a bad idea?", September 20, 2026
- "MCP was always a bad idea?" discussion, Hacker News, September 2026
- Build a Minimal MCP Server, With the JSON-RPC on the Wire, Oluwatosin Aramide
- Show HN: I rawdog a MCP server from scratch in Zig, Hacker News, June 2025
- MCP Went Stateless: Migrating to the 2026-07-28 Spec, Rupa Tiwari, 2026
- Running Handshake and Stateless MCP in the Same Gateway, William Collins, 2026
- The 2026-07-28 specification discussion and the roadmap discussion, Hacker News, July and August 2026
- MCP Transparency Log, independent registry census, August 2026
- State of MCP Server Development: October 2026, LocalCan (vendor)
- The Creators of Model Context Protocol, Latent Space podcast, April 2025
- MCP is a fad, Tom Bedor, December 2025
- MCP vs. CLI Skills for agents: what our eval found, Arize, May 2026
- CLI vs. MCP vs. Code Mode, Port of Context (vendor), March 2026
- MCP vs CLI: Benchmarking AI Agent Cost and Reliability, Scalekit, 2026
- How AI agents behave: lessons from 63M MCP tool calls, PostHog, September 2026
- Scaling an MCP server to 60 million monthly requests, ZenML summary of a Sentry talk
- The next generation of MCP, Cloudflare, August 2026
- Notion's hosted MCP server: an inside look, Notion, July 2025
- MCP deep dive, Pragmatic Engineer, December 2025
- Trading with Claude, Dino Angelov, May 2025
- MCPs are dead, Josh Owens, March 2026
- MCP Hello Page, Luke Lanchester, May 2026
- Optimising MCP server context usage in Claude Code, Scott Spence, September 2025
- Why your MCP server randomly shows no tools: the npx startup tax, 2025
- Fixing slow Zed agent startup times, Ben Swift, December 2025
- The MCP context tax, Okane Land, August 2026
- ChatGPT Developer Mode discussion, Hacker News, September 2025
- postmark-mcp discussion, Hacker News, September 2025
- State of MCP Security 2026, Canopii (vendor), July 2026
- Trust Me, I'm Local: Chrome Extensions, MCP, and the Sandbox Escape, Hacker News, May 2025
- Exposed MCP servers across the internet, Knostic via Hacker News, July 2025
- A First Measurement Study on Authentication Security in Real-World Remote MCP Servers, arXiv, May 2026
- MCP Registry moderation policy
- Shipping an OAuth-protected remote MCP server, SkillDB, June 2026
- Building a Secure MCP Server with OAuth 2.1 and Azure AD, Microsoft ISE, February 2026
- Figma restricts MCP access to whitelisted clients, Hacker News, October 2026
- Introducing ToolBench: A Quality Benchmark for MCP Servers, Arcade, 2026
- From Docs to Descriptions: Smell-Aware Evaluation of MCP Server Descriptions, arXiv, 2026
- From REST to MCP: An Empirical Study of API Wrapping and Automated Server Generation for LLM Agents, arXiv
- A Measurement Study of Model Context Protocol Ecosystem, arXiv, 2025
- Understanding and Measuring MCP Behavior under Misleading Tool Descriptions, arXiv, 2026
- An Empirical Study of Model Context Protocol Applications, arXiv, 2026
- Official MCP Python SDK Flaw Can Let Malicious Servers Steal OAuth Credentials, The Hacker News, September 29, 2026

