Too Many MCP Tools? How to Fix MCP Token Bloat

If your agent feels slower and dumber with every MCP server you install, that is not your imagination. Too many MCP tools is one of the most common performance problems in agent setups today: every connected server injects its full tool catalog -- names, descriptions, and JSON schemas -- into the context window before you type a single word. Stack five or six servers and you can spend tens of thousands of tokens on tool definitions the model will never call.

The fix comes in four layers: prune and scope servers per project, filter individual tools with allowlists, move heavy integrations to code execution with progressive disclosure, and replace knowledge-shaped servers with on-demand skills. This guide walks through each one with concrete commands, starting with how to measure the damage in your own setup.

How too many MCP tools eat your context window

MCP clients like Claude Code, Cursor, and Windsurf handshake with every configured server at session start. Each server responds with its full tool list, and each tool ships three things into your MCP context window:

• A name (create_pull_request, query_database)
• A description explaining when and how to use it
• An input schema describing every parameter, type, and constraint

A well-documented tool easily runs a few hundred tokens once you count the schema. Popular servers ship 15 to 40 tools each. Do the arithmetic on a typical "install everything" setup: five servers times 25 tools times roughly 400 tokens is around 50,000 tokens gone before the first message -- and that cost repeats in every request of every session, because tool definitions stay resident in context for the whole conversation.

The token bill is only half the problem. The other half is MCP tool overload: models select tools less reliably when they must choose among dozens of similar-sounding options. Two servers that both expose a search tool invite wrong-tool calls. Forty irrelevant database tools sitting in context while you edit CSS are pure noise the model must attend past. The result is slower responses, worse tool selection, and less room for the thing that actually matters -- your code.

The failure mode is quiet, which is why it persists. Nothing errors. The agent just gets a little worse with each server you add.

Measuring the damage: auditing your MCP token usage

Before deleting anything, get numbers. Auditing your MCP token usage takes about five minutes:

1. Check the context breakdown. In Claude Code, run /context at the start of a fresh session. It shows how your context window is being spent, including the slice consumed by MCP tools. If tool definitions are eating a double-digit percentage before you have said anything, you have found your problem.

2. List what is connected. Run claude mcp list to see every configured server and where it is configured (user scope vs. project scope). Most people are surprised by what is still in there -- servers installed for a one-off task months ago, still paying rent in every session.

3. Attribute cost per server. Disable one server (the /mcp command in Claude Code lets you toggle servers without editing config), start a fresh session, and run /context again. The difference is that server's per-session tax. Repeat for your heaviest suspects.

4. Compare against usage. For each server, ask: when did the agent last actually call one of its tools? A server whose tools have not fired in two weeks is a pure cost.

Write the numbers down. You will typically find that two or three servers account for most of the overhead, which makes the next steps easy to prioritize. For a deeper walkthrough of how MCP configuration works in Claude Code -- scopes, transports, and config files -- see our Claude Code MCP guide.

Fix 1: too many MCP tools? Prune and scope servers per project

The biggest single win is moving servers from global (user) scope to project scope. A database server belongs in the repos that talk to that database, not in every session you ever start.

1. Remove servers from user scope if they are not universally useful:

claude mcp remove postgres-tools

2. Re-add them at project scope in the repos that need them, which writes a .mcp.json checked into the project:

cd ~/code/api-service
claude mcp add --scope project postgres-tools -- npx -y @example/postgres-mcp

3. Do the same in other tools. Cursor reads a per-repo .cursor/mcp.json, so the same discipline applies: project-specific servers live in project config, and your global config stays close to empty.

A good rule of thumb: your user-scope config should contain at most one or two servers you genuinely use everywhere. Everything else is project-scoped or deleted. When deciding what earns a slot at all, be picky -- our roundup of the best MCP servers for coding is deliberately short, because the marginal value of server number six is usually negative once you price in the context cost.

Fix 2: tool filtering and allowlists

Even a server you legitimately need often ships far more tools than you use. A typical Git hosting server exposes tools for issues, pull requests, releases, workflows, gists, and more -- when all you ever do is read issues and open PRs.

Two mechanisms help here:

1. Server-side toolset flags. Many servers let you load only selected tool groups via environment variables or CLI flags (GitHub's official MCP server, for example, supports enabling specific toolsets). Check your server's docs -- this is the cleanest fix because unloaded tools never enter context at all.

2. Client-side permissions. In Claude Code, settings.json permissions can allowlist exactly the MCP tools an agent may use:

{
  "permissions": {
    "allow": [
      "mcp__github__get_issue",
      "mcp__github__create_pull_request"
    ],
    "deny": [
      "mcp__github__delete_repository"
    ]
  }
}

Permissions primarily gate what the agent can call rather than what gets loaded, so pair them with server-side filtering where available. The combination gives you both a smaller context footprint and a tighter security surface -- a fat, unfiltered toolset is an attack surface as much as a token sink.

Fix 3: code execution with MCP and progressive tool disclosure

The structural fix for MCP token bloat is to stop front-loading tool definitions entirely. Two related patterns are gaining ground in mid-2026:

Progressive tool disclosure. Instead of injecting every schema upfront, the client keeps a lightweight index -- tool names and one-line summaries -- and loads a tool's full definition only when the model actually reaches for it. Some agent runtimes already defer tools this way natively. If your client supports deferred or searchable tools, turn it on: the resting cost of a hundred tools drops to a few lines of index.

Code execution with MCP. Rather than exposing every tool as a first-class definition in context, the agent writes code that calls MCP servers through generated bindings. The model discovers available operations by listing files or searching an API surface, reads only the definitions it needs, and -- crucially -- keeps intermediate results inside the execution environment instead of round-tripping every payload through the context window. A 10,000-row query result gets filtered in code, and only the ten rows that matter reach the model.

If your client does not support either pattern yet, you can approximate it: wrap a heavyweight server behind a thin CLI script that the agent invokes with a single generic tool. One tool definition in context, arbitrary capability behind it. It is less elegant than native support, but the token math works today.

Fix 4: replace always-on servers with on-demand skills

Here is the diagnosis most audits end with: a large share of what people install MCP servers for is not live action at all -- it is knowledge. Documentation lookups, framework conventions, deployment runbooks, code templates. None of that needs a running server or an always-resident tool schema. It needs the right instructions, loaded at the right time.

That is exactly what agent skills do. A skill is a folder with a SKILL.md file at its root, plus any supporting docs, scripts, and templates. The loading model is progressive by design: at rest, only the skill's name and short description sit in context -- roughly one line. The full body loads only when the task actually calls for it, and bundled files are read only as needed. Compare that with an MCP server whose full toolset bills you in every session whether or not it fires. The trade-offs cut both ways -- MCP remains the right choice for live data and real side effects -- and we break the decision down in detail in Claude skills vs. MCP.

Migrating the knowledge-shaped part of your MCP stack takes minutes with localskills.sh:

npm install -g @localskills/cli
localskills login

# Install a skill into every tool you use, from one package
localskills install acme/deploy-runbook --target claude cursor windsurf

One published skill installs into each tool's native format -- .claude/skills/ for Claude Code, .cursor/rules for Cursor, .windsurf/rules/ for Windsurf -- so your team is not maintaining parallel copies per tool. Skills are versioned with rollback, can be public, private, or unlisted, and multi-file packages carry docs, scripts, and templates up to 100 MB per version.

And if you want agents to fetch capabilities themselves, localskills ships an MCP server of its own -- agents can search the registry and install skills over MCP, with OAuth and scoped access. That is the endgame for token bloat: one lightweight server that pulls capabilities on demand, instead of ten heavy ones idling in every session.

FAQ: dealing with too many MCP tools

How many MCP tools are too many?

There is no magic number -- it depends on your context window and how distinct the tools are. Watch for symptoms instead: MCP definitions consuming a double-digit share of /context, the model calling the wrong server's tool, or noticeably degraded reasoning in long sessions. As a practical ceiling, keep the active tool count per session in the low dozens, not the hundreds.

Do MCP tools consume tokens even if I never call them?

Yes. Tool definitions are injected into context when the session starts, so every configured tool costs tokens in every request whether or not it is used. That is why pruning and progressive disclosure matter more than call frequency.

Should I uninstall MCP servers or just disable them?

Scope first, disable second, uninstall last. Move project-specific servers into project config so they load only where relevant. Use your client's toggle (like /mcp in Claude Code) to disable servers for sessions that do not need them. Uninstall anything that has not earned its context cost in weeks.

Are skills a full replacement for MCP servers?

No -- they solve different problems. MCP is the right tool for live data and real side effects: querying a database, opening a pull request, reading production logs. Skills are the right tool for knowledge and repeatable workflows: conventions, runbooks, templates. The token win comes from noticing how much of your current MCP footprint is actually the second category.

---

Ready to move the knowledge half of your MCP stack to on-demand skills your whole team can share? Sign up for localskills.sh and publish your first skill in minutes.

npm install -g @localskills/cli
localskills login
localskills publish