Avoiding tool sprawl, from 530 to 30 MCP tools per session

If you use Claude Code, Codex or Cursor for a while, you collect MCP servers like tabs in a browser. GitHub MCP, Memory MCP, Filesystem MCP, Slack, Notion, Stripe, Brave Search, plus two or three of your own. Suddenly you have 200+ tools in context, your agent picks the wrong one, hallucinates tool names, or breaks off the plan because it gets lost. That is called tool sprawl, and Anthropic published the official MCP Client Best Practices in April 2026 for exactly this.

This playbook brings you 10 steps to clean tool routing. You learn how to assign tools per agent, how to keep the context lean even with 30 servers installed, and how you even notice you are in the sprawl in the first place. Works with Claude Code, Cursor, Codex and any MCP host that supports tool filtering.

Before you start: look into lesson L4-06 "MCP discovery and marketplaces" and L6-07 "Multi-agent orchestration". They have the concept of why, this is the practice of how.

Step 1, take inventory

Count what you have connected. In Claude Code you run claude mcp list, in Cursor you look in ~/.cursor/mcp.json, in Codex the same under ~/.codex/config.toml. Write down all servers, then the tool count per server. GitHub MCP alone brings 19 tools, Memory brings 50+, a full suite quickly hits 200.

My own setup: 38 MCP servers, 530 tools if they all loaded at once. But they do not, because I filter them per task. Without filtering that would be 80 percent of my token budget just for tool descriptions.

Step 2, understand the tool-sprawl problem

Three symptoms show you that you are in the sprawl. First, the agent writes completely hallucinated tool names ("I call github_create_issue_with_assignees" even though the tool is called create_issue). Second, the agent picks the right tool but with wrong arguments ("I pass repo_name" even though the parameter is called repository). Third, the agent loses the plan ("Wait, I check first with tool A, then with tool B, then with tool C..." and trickles away into meta-steps).

All three symptoms have the same cause: too many tool descriptions in context, the attention mechanism spreads out. Anthropic talks about "token drift" and recommends actively using tool filtering.

Step 3, the pickMcp pattern as a mental model

Instead of loading all servers into context at once, you give each agent or each task only the 3-5 servers it really needs. With me the function is called pickMcp(role) and returns a typed list per role.

Example: my research agent gets only mcp-research (web search), mcp-nex (memory) and mcp-notion (output). My code-review agent gets only mcp-github, mcp-nex (memory for earlier reviews), mcp-filesystem. No agent gets everything.

The pattern works without programming too. You can simply set up profiles and switch between them manually.

Step 4, set up profiles in Claude Code

Claude Code 2.1.119 introduced persistent /config, with it you can have a different MCP config per workspace. Set up three or four profiles: research, code, ops, writing. Each profile has its own ~/.claude/profiles/<name>/mcp.json.

In each profile you define only the servers that belong there. Research gets search tools and memory, Code gets GitHub plus filesystem plus memory, Ops gets server connections plus memory, Writing gets only memory plus Notion.

Switch with claude --profile=research. Claude loads only the servers from the profile, the rest stays in the cupboard.

Step 5, filter tools within a server

Some servers bring 50+ tools even though you only need 5 of them. GitHub MCP for example: I use create_issue, search_issues, get_pull_request, create_pull_request, merge_pull_request. The other 14 (workflows, releases, org management) I rarely need.

More modern MCP servers support "toolsets" or "filter flags" at start. GitHub MCP for example --toolsets=issues,pull_requests. Check your server's docs for --enabled-tools or --disabled-tools. If the server cannot do that, it is a wish for the maintainer.

Step 6, progressive disclosure as an emergency brake

If you really need many tools but not at the same time, progressive disclosure helps. Concept: you start with a meta list ("which categories do you have there?") and the agent asks for the tools of a category only on demand.

Solo.io published a pattern on this in April 2026. In practice: you build a small wrapper MCP that first returns a list of server names. The agent picks a server, then you deliver the tool list of that server. Costs one round trip, saves 80 percent of tokens in the default case.

Not everyone needs this. Whoever gets by with 30 tools can skip this step.

Step 7, memory as a sprawl reducer

Memory is your best friend against tool sprawl. Instead of three tools that can all "write notes" (Notion, Apple Notes, Markdown), you have a single Memory MCP that covers everything. Instead of four tools that do "search" (Google, Bing, Brave, Perplexity), you have mcp-research with a unified interface.

That is the centralization lever. Check in your list from step 1 where you have redundant tools and consolidate.

Step 8, track down naming conflicts

If two servers both have a tool called search, the agent hallucinates for sure. That is the underestimated killer. GitHub MCP has search_issues, Brave Search has search, some memory servers have search_memories. The agent loses track of who can do what.

Fix: set a clear tool prefix per MCP server if the server supports it (github_search_issues instead of search_issues). If not, then at least watch out when assembling the profiles that not two search tools land in the same profile.

Step 9, measure your own setup

Build yourself a small measurement script. With me it runs like this: after each session I dump the number of tool calls plus the tool names plus whether the call was successful (no hallucination error). From that I see monthly which tools are never used, which are often hallucinated, which are always used in combination with which others.

Tools that were used zero times in 30 days: out of the profile. Tools that were hallucinated more than 3 times in 30 days: check naming or improve docs.

Some MCP hosts have built-in telemetry, others do not. If not, your own logging on the server wrapper.

Step 10, default profile as self-discipline

My default profile has exactly three servers. mcp-nex (memory), mcp-filesystem (read/write local), mcp-research (web). 30 tools in total. If I need more, I switch actively with claude --profile=....

This decision "default is small, more only on request" is the most important discipline. Beginners want everything always on hand just in case. Pros know that less context = better results, and the switch between profiles is a matter of 5 seconds.

What comes next

If you have not set up memory yet, go via the playbook "Memory portabel nutzen". If you want to build your own MCP servers, lessons L6-01 to L6-08 plus the playbook "Erster MCP-Server in 90 Minuten". If you want to go deeper into sub-agents (each with its own profile), the playbook "Erster Sub-Agent in 30 Minuten".

Sources: Anthropic MCP Client Best Practices, modelcontextprotocol.io/docs/develop/clients/client-best-practices. Solo.io progressive disclosure article April 2026. Own pickMcp pattern documented in agents/lib/mcp-config.ts.