MCP server instructions are silently truncated when multiple servers are configured

Status Fixed / completed

Maintainer reply ✓ Yes — bcherny

Activity 5 comments · opened Apr 4, 2026 · closed Aug 17, 2026

💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

Problem

When multiple MCP servers are configured (e.g., context7 + deepwiki + serena), the MCP server instructions block in the system prompt is silently truncated. The last server's instructions get cut off mid-sentence with no warning.

Reproduction

Configure 3 MCP servers with non-trivial instructions (context7, deepwiki, serena). Capture the raw API request and inspect the system-reminder block containing # MCP Server Instructions.

Observed: The instructions for the last server (serena) are truncated mid-sentence:

use `find_symbol` with name path pattern `Foo/__init__` and `includ… [truncated]

The total MCP instructions block is ~4KB before truncation occurs. The full serena instructions are ~4KB+ on their own, but only ~2KB makes it through because context7 and deepwiki consume the first half of the budget.

Impact

Silent data loss: Critical usage instructions for MCP servers are dropped without any warning to the user or the server.
Unfair ordering: Servers listed later are more likely to be truncated. The ordering is not user-controllable.
Degraded behavior: The model loses important guidance on how to use the truncated server's tools effectively (e.g., advanced query patterns, editing workflows, memory system usage).
No workaround for server authors: MCP servers cannot know their instructions are being truncated, and have no way to prioritize which parts to keep.

Expected Behavior

MCP server instructions should not be silently truncated, or at minimum a warning should be shown to the user.
The budget should be large enough to accommodate multiple servers with reasonable instructions.
Ideally, users should be able to configure the instruction length limit.

Environment

Claude Code CLI (latest)
macOS
3 MCP servers configured: context7, deepwiki, serena

View original on GitHub ↗

5 Comments

sfitts · 4 months ago

Hitting the same silent-truncation visibility issue from the MCP-server-author side. When designing a server's instructions block, there's no way to know at runtime that you've exceeded the budget — the only signal is the model behaving as though guidance you wrote isn't present, which is hard to trace back to truncation.

A startup warning identifying the affected server, original byte size, and effective cap would resolve the visibility problem without changing the truncation policy itself. Cheap to add, and it would let server authors trim with confidence rather than discovering the cap by stumbling into broken behavior.

Also +1 to your point that ordering across multiple servers compounds the problem — even an author who keeps their own block under 2KB has no way to know how much budget remains once other servers in the user's config consume it first.

narviii · 3 months ago

My claude asked me to write it, i confirm:

Confirming this same root cause affects Cowork (Anthropic's desktop app, research preview) with a more severe failure mode: when the cumulative MCP instructions budget is exceeded, later-loaded servers get their entire instructions block dropped from the system prompt rather than truncated. No warning surfaced anywhere.
Reproduced with three connected MCPs (computer-use, Microsoft Clarity, a custom server roboOwlMCP with ~2.7KB instructions). The custom server's instructions were completely absent until I disconnected computer-use, at which point they appeared in a fresh conversation. The model has no signal that anything was dropped — it just behaves as if the server never published instructions.
Additionally for custom URL-added MCPs: tool namespaces use the server UUID rather than the configured friendly name, which means the model can't find the server when searching by name and can falsely conclude it isn't connected.

khalidodev · 2 months ago

I can confirm that I am not seeing MCP server instructions come through. I just have a very short server instructions, but nothing passes through to the agent.

I understand context bloat issues and Anthropic has to smartly manage the total size, but I would like an option to prioritize a remote MCP and not truncate its instructions.

Claude code says:

stdio servers inject fine (confirmed in my own session); a remote OAuth Streamable-HTTP server's instructions drop entirely; plus this truncation ceiling — looks like multiple distinct code paths.

Longer comment at https://github.com/anthropics/claude-code/issues/23808

rilian · 20 days ago

hi, any updates from Claude Code team ?

bcherny collaborator · 15 days ago

Thanks for the detailed report. I reproduced this on 2.1.233 with three stdio servers carrying ~0.9 KB, ~1.2 KB and ~4.2 KB of instructions: the first two came through intact and the third was cut at 2,048 characters with the … [truncated] marker.

What's actually happening is a per-server cap, not a shared budget: Claude Code truncates each MCP server's instructions (and each tool description) at 2 KB, independent of how many servers are configured or their order. Your serena instructions are ~4 KB on their own, so they hit the cap regardless of context7/deepwiki. This has been the intended behavior since 2.1.84 and is documented here: https://code.claude.com/docs/en/mcp#for-mcp-server-authors ("Claude Code truncates tool descriptions and server instructions at 2KB each. Keep them concise... put critical details near the start").

Today the truncation is only reported in the debug log (claude --debug), so we agree the visibility ask is fair — a warning in /mcp or at startup, and possibly a configurable cap, are reasonable follow-ups. The reports in the comments about remote (HTTP/OAuth) servers' instructions being dropped entirely are a different issue and are tracked separately.

🤖 Generated with Claude Code