Why does Claude Code stall when I install too many MCP servers?

Claude Code reads the tool list into its system prompt on session start. Every tool adds 200-400 tokens of schema + description. Above ~25 advertised tools (counting both built-ins and MCP), tool-selection accuracy drops sharply and cold sessions can freeze or thrash. The cause is the tool-selection step itself, not the tools — the model picks worse from a longer list, and the manifest displaces working context. Fix: configure your MCP server to advertise only the subset you actually use, or use a host that supports lazy tool loading (Anthropic's Tool Search). Sverklo ships SVERKLO_PROFILE=core as the default in v0.20.9+ which exposes 6 tools instead of 36.

How many MCP tools is too many for Claude Code?

The empirical threshold is around 25 tools per session on cold start. Sverklo's reproducer used a single server with 36 tools; the stall was consistent. Below 25, selection accuracy stays acceptable. Above 35-40, the manifest itself starts to displace 5-10% of usable context window even before any tool fires. Multiple MCP servers stack — three servers with 12 tools each is 36, which hits the same threshold.

What's in the sverklo core profile?

Six tools covering 80% of real code-intelligence sessions: sverklo_status (is the index alive?), sverklo_search (concept-level retrieval), sverklo_lookup (find a symbol by name), sverklo_overview (codebase map by PageRank), sverklo_refs (find callers of a symbol), sverklo_impact (refactor blast radius). The remaining 30 specialized tools — audit, diff-aware review, ctx-handle ops, memory, etc. — are available via SVERKLO_PROFILE=lean, research, review, or full when needed.

How do I verify my MCP server actually works with Claude Code?

v0.20.9 adds sverklo doctor with a full MCP round-trip probe: it spawns the server, sends initialize, then tools/list, then tools/call sverklo_status, and reports each step. A passing doctor run prints 'MCP dispatch verified end-to-end' — this is the same path Claude Code takes on every cold session, so passing here is positive proof the wiring works. Doctor also surfaces the active SVERKLO_PROFILE so users on stale 36-tool configs see the warning.

Can I still use the full sverklo tool surface when I need it?

Yes, the profile is a runtime env var. Set SVERKLO_PROFILE=full to advertise all 36 tools, or use lean (11), research (18), or review (10) for narrower workflows. The default in v0.20.9+ is core (6) because it's the lowest-token profile that still answers 80% of code-intel sessions. Switch profiles with .mcp.json env: { SVERKLO_PROFILE: 'lean' } and restart your AI agent.

/* engineering · 2026-05-10 · tool-selection failure */

Claude Code Stalls Above ~25 MCP Tools — Measured, Fixed in v0.20.9

2026-05-10 ~6 min read Part of: Claude Code troubleshooting pillar

Reports of Claude Code freezing on tool selection when an MCP server exposes "too many" tools have been stacking up across r/mcp, r/ChatGPTCoding, and our own issue tracker for weeks. This week a user pushed back with measurements from his proxy setup. We reproduced the stall, shipped a 6-tool default profile in v0.20.9, and added an end-to-end MCP dispatch probe to sverklo doctor so the fix is verifiable on every fresh install.

The symptom

You install an MCP server. You restart Claude Code. The tool list shows up in /mcp. You ask a question that should obviously route to one of the new tools. Claude Code either ignores them and falls back to grep, or it sits visibly thinking longer than it should before picking the wrong one.

"I've been trying to use this for the past few hours but even with the giant block in the agent file I cannot get Claude Code to actually use it." — Ian Costa, on Dan Luu's X thread, 2026-05-09

This is a tool-selection failure, not an install failure. The MCP wiring is correct — tools/list returns the tools, tools/call works on direct invocation. What breaks is the agent's selection step: faced with a long list of options, the model either freezes, picks the safest fallback (grep), or thrashes between candidates.

The measurement

We tested with sverklo's full profile (36 tools advertised) stacked alongside Claude Code's built-ins (~10-15 depending on session). The combined tool list crosses the threshold above which selection accuracy degrades.

Profile	Tools	System prompt	Stall on cold session
full	36	8,016 tokens	Yes (reproducible)
research	18	3,950 tokens	Sometimes
lean	11	3,469 tokens	No
review	10	2,788 tokens	No
core (new default)	6	1,522 tokens	No

The empirical threshold sits around 25 advertised tools per session. Below that, selection works. Above it, you start losing routing accuracy. Above 35-40, the manifest displaces 5-10% of usable context window before any tool fires.

Industry signal corroborates this — Atlassian's mcp-compressor write-up claims 70-97% reduction is achievable; Anthropic's Tool Search went GA partly to address this; The New Stack reports cases of "55-77K tokens before any work begins" with multiple MCP servers stacked.

The fix path

v0.20.9 ships SVERKLO_PROFILE=core as the default in .mcp.json when you run sverklo init. Six tools, 1,522 tokens, no manual env var to remember:

npm i -g sverklo@latest
cd your-project
sverklo init
sverklo doctor

For users on a pre-v0.20.9 install, sverklo init includes a soft migration: if your existing .mcp.json has the sverklo entry but no env block, it appends SVERKLO_PROFILE=core automatically. If you already set a profile, it leaves your choice alone.

What's in the core profile

Six tools that cover the 80% of code-intel sessions where users actually reach for an MCP server:

sverklo_status — index health and "is this thing alive?" check
sverklo_search — concept-level retrieval ("where does auth happen?")
sverklo_lookup — find a symbol by name with file:line
sverklo_overview — codebase map ranked by PageRank
sverklo_refs — find callers of a symbol
sverklo_impact — blast radius for a refactor

The remaining 30 tools — audit, diff-aware review, memory, concept clustering, ctx-handle ops — stay available via SVERKLO_PROFILE=lean | research | review | full when those workflows are active.

Verifying it works

The other half of v0.20.9 is sverklo doctor with a full MCP round-trip probe:

$ sverklo doctor
sverklo doctor — checking MCP setup

  ✓ sverklo binary               /opt/homebrew/bin/sverklo
  ✓ version                      sverklo v0.20.14
  ✓ embedding model              86MB at ~/.sverklo/models/model.onnx
  ✓ .mcp.json (project root)     sverklo configured (profile: core)
  ✓ permissions auto-allow       sverklo tools won't prompt for approval
  ✓ prefer-sverklo instructions  installed in CLAUDE.md
  ✓ MCP handshake                responds correctly (protocol 2024-11-05)
  ✓ MCP tools/list               6 tools advertised (sverklo_status present)
  ✓ MCP tools/call               sverklo_status returned 1021 chars — dispatch round-trip works

All checks passed — MCP dispatch verified end-to-end.
If Claude Code was running before init, restart it to pick up the new config.

The new probe runs the same three calls Claude Code makes on every cold session: initialize → tools/list → tools/call sverklo_status. Passing this is positive proof the wiring works, not just that the binary speaks JSON-RPC. The previous "MCP handshake responds correctly" check only verified the first step, which led to "doctor passed but Claude still doesn't call sverklo" reports.

What this doesn't fix

Profile-filtering shrinks the tool list one server advertises. It doesn't fix:

Multiple MCP servers stacked. If you run sverklo (6) + filesystem (4) + GitHub (8) + Linear (6), you're back to 24 tools combined. The fix at that layer is host-side lazy loading (Anthropic's Tool Search) or gateway-level code mode (Bifrost, Cloudflare's pattern).
The agent ignoring its instructions. If Claude Code reads your CLAUDE.md but still routes to grep, the snippet is too soft. Sverklo's init writes a MUST/NEVER imperative block as of v0.20.9 to mitigate this.
Tool descriptions that are too long. Some MCP servers ship 1K+ tokens per tool. Even 6 such tools can blow past 6K of overhead. Sverklo's tool descriptions are deliberately short; check yours.

Try the fix

npm i -g sverklo@latest
cd your-project && sverklo init    # writes profile=core
sverklo doctor                       # verifies end-to-end MCP dispatch

One install, one verification. github.com/sverklo/sverklo · Full troubleshooting pillar · Deep dive: SVERKLO_PROFILE vs Code Mode