What an MCP server costs you in tokens

Most advice about building an MCP server stops at "it works." Your tools are discoverable, the agent calls them, the demo goes well. What the demo does not show you is the standing charge.

Tool definitions are not a one-time setup cost. They sit in the context window on every turn, so every description you wrote and every JSON Schema property you declared is paid for again each time the agent thinks. Anthropic's own documentation puts a number on it: a typical multiserver setup of GitHub, Slack, Sentry, Grafana, and Splunk consumes roughly 55,000 tokens in tool definitions before the model does any work at all.

That is the part people eventually notice, because it shows up on an invoice. The part they do not notice is that the same bloat degrades the agent's ability to pick the right tool. Anthropic is explicit that tool selection accuracy starts to fall once you exceed thirty to fifty available tools. So the cost of a sprawling MCP server is not only money and latency. It is correctness.

The first bill: Definitions, charged every turn

A tool definition is a name, a natural-language description, and a JSON Schema for its inputs. Something like this, in the shape a model actually sees:

  
gdrive.getDocument
     Description: Retrieves a document from Google Drive
     Parameters:
                documentId (required, string): The ID of the document to retrieve
                fields (optional, string): Specific fields to return
     Returns: Document object with title, body content, metadata, permissions, etc.
  

That is maybe eighty tokens. Harmless. Now multiply by the fifty-odd tools a mature server exposes, add four more servers, and you are at Anthropic's 55,000 before your user has typed a character. Connect an aggregator with hundreds of tools and you are processing hundreds of thousands of tokens as a precondition for reading the request.

The thing that makes this a standing charge rather than a setup fee is where the definitions live. They go into the system prompt prefix, which means they are resident for the whole conversation, not amortised across it. A hundred-turn session pays for them a hundred times.

The second bill: Intermediate results

The definitions are the fixed cost. The variable cost is every byte of data that passes through the model on its way between two tools.

Take a request like "download my meeting transcript from Google Drive and attach it to the Salesforce lead." With direct tool calls, the agent reads the transcript into context, then writes the entire transcript back out again as an argument to the Salesforce call. The document flows through the context window twice. For a two-hour sales meeting, Anthropic estimates that as an extra 50,000 tokens for a task whose useful output is one field update.

Two things get worse from here. Large enough payloads simply exceed the context window and the workflow breaks. And when a model is asked to copy a large structure verbatim from one call into the next, it sometimes gets it wrong, which converts a cost problem into a data-integrity problem.

The bill that is not about money

If the story were only cost, you could shrug and pay it. The reason to care is the accuracy cliff.

Anthropic's documentation states plainly that Claude's ability to select the correct tool degrades once more than thirty to fifty tools are available. This matches the intuition anyone who has written a large prompt already has: a model choosing among fifty-one plausible options behaves worse than the same model choosing among five, and the fifty-one are not a neutral background. They are actively competing for the decision.

That reframes the design problem. A generous tool surface is not a gift to the agent that it can ignore at no cost. Every tool you add is a small tax on the selection quality of every tool you already had. Anthropic's threshold for reaching for mitigation is worth memorising: consider deferred loading at ten or more tools, or when definitions exceed 10,000 tokens, and treat plain tool calling as fine only below ten tools with small definitions.

Why a good REST API makes a bad MCP server

The failure mode is mechanical. Someone points an OpenAPI converter at a mature REST API, and a design virtue on one side of the boundary becomes a liability on the other.

REST APIs are generous on purpose. Hundreds of small, composable endpoints are correct when the consumer is a developer writing deterministic code, because programmatic iteration is nearly free: a human reads the docs once and their code chains get_user(), get_orders(user_id), and get_order_details(order_id) at network speed. More choice is straightforwardly better.

Hand that same surface to an agent and the economics invert. Agentic iteration is expensive in a way programmatic iteration is not. Each hop costs a model turn, each turn re-pays the full definition bill, and each intermediate result transits the context window. Your hundred well-factored endpoints become a hundred tool definitions competing for one decision.

The rule that follows is short. Design tools around what someone is trying to accomplish, not around your internal API structure.

• Three tools (get_user, get_orders, get_shipments) force three round trips and make the model hold intermediate state in conversation history.
• One tool (track_order(email)) calls all three endpoints internally and returns "Order #12345 shipped via FedEx, arriving Thursday."

Same outcome, one turn, one definition, nothing to carry between calls. Your REST API keeps serving your web app unchanged; the MCP server is a separate, deliberately narrower interface.

!!For more on this see MCP vs. REST: What's the right way to connect AI agents to your API?!!

Four ways to cut the bill

In rough order of how much you get for the effort.

1. Expose fewer, larger tools

The cheapest option, because it requires no new infrastructure. Identify the handful of workflows people actually ask an agent to perform, build one outcome-shaped tool per workflow, and do not expose the rest. Everything below is mitigation for a tool surface you have already decided you need. This is the option that prevents the problem.

2. Deferred loading and tool search

Rather than loading every definition up front, mark tools with defer_loading: true and let the model search a catalog for what it needs:

  
{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": { "location": { "type": "string" } },
    "required": ["location"]
  },
  "defer_loading": true
}
  

The model searches, the API returns matching tools as tool_reference blocks and expands them into full definitions inline. Two search variants exist: a regex variant where the model writes Python re.search() patterns, and a BM25 variant that takes natural language. Anthropic reports this typically cuts definition overhead by more than eighty-five percent, loading only the three to five tools a given request needs, and it scales to 10,000 deferred tools per request.

If your tools arrive through the MCP connector, you do not set defer_loading per tool. You set it once on the mcp_toolset entry's default_config for the whole server, or per tool in its configs.

3. Code execution, so results never transit the model

This addresses the second bill. Instead of the model calling tools directly, present the servers as a code API on a filesystem and let the model write a program:

  
servers
├── google-drive
│   ├── getDocument.ts
│   └── index.ts
└── salesforce
    ├── updateRecord.ts
    └── index.ts
  

The Drive-to-Salesforce task becomes a few lines, and the transcript never enters the context window:

  
import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

const transcript = (await gdrive.getDocument({ documentId: 'abc123' })).content;
await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});
  

The model discovers tools by listing directories and reading only the files it needs, which is progressive disclosure by another route. Anthropic reports this taking one workflow from 150,000 tokens to 2,000, a 98.7 percent reduction. Cloudflare published similar findings under the name Code Mode.

The same pattern fixes large reads. Fetch a 10,000-row sheet, filter it in the execution environment, and log five rows. The model sees five.

This is the most powerful option and the most expensive to operate, which Anthropic says directly: running model-generated code needs a real sandbox, resource limits, and monitoring. Do not adopt it because the percentage is impressive. Adopt it when your intermediate payloads are genuinely large.

4. Let clients cache your catalog

This one is new, and it is free. The 2026-07-28 MCP revision requires ttlMs and cacheScope on the results of tools/list, prompts/list, resources/list, resources/read, and resources/templates/list. Set a sensible TTL and clients stop re-fetching your catalog on every reconnect.

The revision also says servers should return tools from tools/list in a deterministic order, and this is the detail to actually act on. Deterministic ordering keeps upstream prompt caches stable across reconnects. If your tool order comes out of a map iteration and varies between calls, you are invalidating your users' prompt caches every time they reconnect, and paying for it in their latency and their bill rather than yours. It is a one-line fix that nobody makes because nothing visibly breaks.

Gotchas worth knowing before you implement

• defer_loading controls context, not payload. You still send every tool's full definition in the tools array on every request, deferred ones included, because the API needs them server-side to run the search and expand references. It reduces what the model reads, not what you transmit.
• At least one tool must stay non-deferred, normally the search tool itself. Deferring everything returns a 400. Keep your three to five most-used tools loaded so common requests skip the search entirely.
• A deferred tool cannot carry cache_control. That combination is a 400. Put your cache breakpoint on a non-deferred tool.
• Prompt caching survives deferral. Deferred tools are excluded from the system-prompt prefix, and discovered tools are appended inline in the conversation, so the prefix stays untouched.
• Namespace your tool names. Prefixing by service or resource (github_, slack_) means one search matches the whole group. Unprefixed names make the model search repeatedly.
• Tool search is not billed as a separate server tool. The definitions it loads count as ordinary input tokens.

A budget you can apply

If you publish an MCP server, this is your users' bill

The asymmetry is worth sitting with. When you publish an MCP server, your tool count is a tax on every turn of every conversation your users have, and none of it appears on your invoice. It appears on theirs, along with the accuracy cost, and they will experience it as your server being slow and your tools being unreliable.

That argues for treating your tool surface as a product decision rather than a coverage exercise. The same thinking you would apply to a UI applies here: what is the smallest set of things that lets someone accomplish what they came for. The user happens to be a model.

There is one place the 2026-07-28 revision helps with this beyond caching. Because method and tool names now travel in the Mcp-Method and Mcp-Name HTTP headers, a gateway can route, meter, and rate-limit per tool without parsing a JSON-RPC body. Per-tool authorization policies get the same benefit, which matters once different tools in one server need different scopes. If that is the layer you are working on, AuthKit handles OAuth 2.1 for MCP, and we wrote up the gateway problem in the hard part of an MCP gateway is auth.

Frequently asked questions

How many tokens do MCP tool definitions use?Anthropic reports roughly 55,000 tokens for a typical five-server setup of GitHub, Slack, Sentry, Grafana, and Splunk, consumed before the model does any work. A single tool definition is usually tens to low hundreds of tokens, so the total scales with tool count and schema verbosity.

Are tool definitions charged once per session or once per turn?Per turn. Definitions live in the system prompt prefix and are resident for the whole conversation, so a long session pays for them repeatedly. Prompt caching reduces the cost but does not remove it.

How many tools is too many for an MCP server?Tool selection accuracy begins degrading past thirty to fifty available tools. Anthropic suggests deferred loading at ten or more tools, or when definitions exceed 10,000 tokens.

What is defer_loading?A flag that keeps a tool's definition out of the context window until the model discovers it through a search. You still send the full definition in every request; it changes what the model reads, not what you transmit.

Does code execution with MCP really cut tokens by 98 percent?Anthropic reports one workflow going from 150,000 tokens to 2,000. The saving comes mostly from intermediate results staying in the execution environment instead of passing through the model, so the gain is largest when payloads are large and negligible when they are small.

How do I reduce MCP token usage without new infrastructure?Expose fewer, outcome-shaped tools; return tools from tools/list in a deterministic order; and set a sensible ttlMs. None of those require a sandbox or a gateway.