If you use Claude Code, OpenAI Codex CLI, Cursor, or VS Code Copilot with Model Context Protocol (MCP) servers, your context window and prompt cache are exposed to three silent failure modes:
-
Startup Schema Bloat (
tools/list): Connecting 3 common MCP servers (github,postgres,playwright) injects 60+ tool JSON schemas (~20,000+ tokens) into every single turn. -
Oversized Stdio Frame Teardowns (
tools/call): Returning >= 8 MiB in Claude Code kills the stdio server process with<error>Connection closed</error>(anthropics/claude-code#105703); returning >= 16 MiB in Codex CLI discards the frame silently until the 300s tool timeout expires (openai/codex#60383). -
Silent Prompt Cache Invalidations & Config Drift: Reordered MCP tools, dynamic prefixes before
cache_control, or mid-session"disableAllHooks": trueedits (anthropics/claude-code#106225) silently burn tokens or drop guardrails.
We built three zero-telemetry open-source tools to inspect and prevent all three:
-
@framy2/ctxwise(v1.2.0) — Context Firewall, Multi-Editor MCP Auditor & CI Budget Guard (Apache-2.0) -
@framy2/mcp-diet(v0.1.1) — Stdio MCP Proxy withtools/listTree-Shaking, 8 MiB Spill-to-Disk Crash Guard & Secret Redaction (MIT) -
@framy2/agent-wire-tap(v0.2.0) — Local Wire Contract Tester & Live--passthroughPrompt-Prefix Cache-Miss Debugger (MIT)
1. Put Your MCP Servers on a Diet (@framy2/mcp-diet)
{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@framy2/mcp-diet@0.1.1",
"--read-only",
"--max-desc", "160",
"--max-result-kb", "512",
"--redact-secrets",
"--",
"npx", "-y", "@modelcontextprotocol/server-github"
]
}
}
}
mcp-diet sits on stdio between the host CLI and the upstream MCP server:
- Spills
>= 512 KiBtool outputs to a local temp file and returns a compact< 2 KBpreview so Claude Code (8 MiB) and Codex (16 MiB) never tear down the pipe. - Deterministically sorts tool schemas so prompt prefix caches stay warm.
- Redacts leaked credentials (
sk-ant-*,sk-proj-*,ghp_*,AKIA*, DB passwords) before they reach the model transcript.
2. Audit Every Editor & Lock CI Budgets (@framy2/ctxwise v1.2.0)
# Probe stdio MCP tools safely (works on Windows without shell: true) & profile token weight
npx @framy2/ctxwise mcp-xray --probe-stdio
# Check CLAUDE.md, .claude/rules/*.md, AGENTS.md, .cursor/mcp.json, and .vscode/mcp.json parity
npx @framy2/ctxwise agents --fail-on-divergence
# Scan for leaked secrets, Trojan Unicode, disableAllHooks, and unpinned `npx -y` MCP runners
npx @framy2/ctxwise shield --strict --sarif ctxwise.sarif
# Enforce ctxwise.budget.yaml across Claude, Codex, and Cursor without double-counting synced rules
npx @framy2/ctxwise budget
3. Pinpoint Exact Turn-Over-Turn Cache Misses (@framy2/agent-wire-tap v0.2.0)
# CI contract test at $0.00 API cost (mock mode)
npx @framy2/agent-wire-tap \
--assert-contains "AGENTS.md" \
--assert-not-contains "sk-ant-" \
--assert-max-bytes 32768 \
--assert-max-tools 12 \
-- codex exec "ping"
# Live transparent pass-through proxy (streams SSE & detects prefix divergence block-by-block)
npx @framy2/agent-wire-tap --passthrough https://api.anthropic.com --port 8787
--passthrough keeps credentials strictly in memory ([REDACTED] in traces/logs) while hashing each prefix segment (model, tools[], system[], messages[]) and flagging the exact firstDivergentLayer / firstDivergentIndex whenever a mutation breaks a cache_control breakpoint.
Try the Client-Side Calculator
Paste your .mcp.json, .vscode/mcp.json, CLAUDE.md, or AGENTS.md right in the browser (100% local, zero uploads):
Top comments (17)
The 8 MiB teardown is a good reminder that the cheapest fix is on the server side: don't build a tool that can return that much in the first place.
Disclosure: I maintain an open-source video editor (CutVoke) that Claude Code / Codex drive over MCP, and media is the worst case for this, since one careless "show me the timeline" could mean frames, waveforms, transcripts. A few rules we settled on:
deanlee's point about the spill preview is the important follow-on. If a proxy has to cut a response down, a preview with section names and offsets lets the agent ask for exactly the part it needs instead of paging through the temp file blind. Tools designed small don't need the safety net as often, but the net is still worth having for third-party servers you don't control.
Couldn't agree more — CutVoke's pattern of returning lightweight structural handles + revision IDs and keeping binary/media previews explicitly bounded on separate tools is the right design from the server side up.
For third-party MCP servers you can't modify, we just took yours and
@deanlee's suggestion and shipped @framy2/mcp-diet v0.2.0 (017ed7d, github.com/FramY2/mcp-diet): oversizedtools/callresponses now emit aStructural Section & Offset Index(JSON key/array counts, Markdown headings, or log headers with exact line + UTF-8 byte spans, plus head/tail previews) alongside a sandboxed read-onlymcp_diet_read_spilltool supportingjsonPointer,startLine/endLine, andoffsetBytes/maxBytesslicing. Appreciate the feedback!Nice, that was quick. The line and byte spans are the part I'd have wanted most: the agent can jump straight to the section it needs instead of guessing offsets.
One thing I'd be curious about once it sees real traffic: how often agents actually call mcp_diet_read_spill after getting the index, versus answering from the head/tail preview alone. That would tell you whether the preview size is about right.
Completely agree — knowing how often agents actually follow up with
mcp_diet_read_spillvs answering straight from the index + head/tail preview is the exact signal needed to tune default preview lengths.Just added lightweight local session telemetry in
@framy2/mcp-diet@0.3.0(e6b45b2) to measure exactly that without adding extratools/listbloat:toolCallsInspected,byteSpillsTriggered,imageDimensionSpillsTriggered,spillReadsCount,uniqueSpillsReadCount,previewOnlySpillsCount, andspillReadFollowUpRate.proxy.getTelemetry(), inside themcp_diet_statustool output, and printed to stderr on exit with--report-stats.That's a nice set of counters, and keeping it out of tools/list is the right call. spillReadFollowUpRate next to previewOnlySpillsCount should make the preview-length question answerable with data instead of guesses.
One small thought: if the rate turns out very different per upstream server, a per-server breakdown might be worth having, since a server that returns big logs and one that returns big JSON probably want different preview sizes. Thanks for the update.
Completely agree — a server streaming stack traces or build logs has a very different follow-up profile than one returning structured JSON arrays.
Just pushed that into
@framy2/mcp-diet@0.3.1(3c933be,github.com/FramY2/mcp-diet):getTelemetry(),mcp_diet_status, and--report-statsnow includeupstreamServer({ name, version }captured automatically frominitialize) alongside abyToolbreakdown (toolCallsInspected,byteSpillsTriggered,uniqueSpillsReadCount,previewOnlySpillsCount, andspillReadFollowUpRateper tool name).--preview-chars <chars>): Lets you give a log server wrapper--preview-chars 2400and a JSON-heavy wrapper--preview-chars 600directly in.mcp.jsonbased on what each tool's follow-up rate shows.Thanks again for the sharp design feedback!
Nice, per-tool numbers under upstreamServer is exactly the shape I was hoping for, and putting --preview-chars in the per-wrapper config keeps the tuning next to the server it's for. Looking forward to seeing what the follow-up rates actually look like once a few people run it on real log-heavy servers.
Images hit a different wall well before 8 MiB. Once a request carries many images, Claude Code rejects anything over 2000px on a side with "An image in the conversation exceeds the dimension limit for many-image requests (2000px). Start a new session with fewer images." and that session stays stuck. A screenshot tool returning a raw fullPage PNG trips it long before the pipe dies.
Downscaling inside the server costs nothing extra, the model shrinks anything past 2576px on the long edge anyway (1568 on older models), so the extra pixels are paid for and thrown away.
Does mcp-diet spill image content blocks too, or only text?
Spot on — thank you for calling out the
2000pxmany-image lockup! That dimension rejection hits well below the 8 MiB stdio disconnect threshold and can wedge a multi-image session from a single full-page PNG screenshot.To answer honestly: in
v0.2.0,mcp-dietonly summarized and spilledimageblocks ([image block (mime, N base64 chars)]) when the byte threshold (--max-result-kb) was exceeded, so a<512 KiB2560x3200screenshot slipped straight through untouched.Just shipped
@framy2/mcp-diet@0.3.0(e6b45b2, github.com/FramY2/mcp-diet) to handle this directly:PNG,JPEG,GIF,WebP): inspectsimageblocks even on small payloads (< 10 KiB) against--max-image-dim(default2000,0disables).imageexceeding2000pxon width or height is saved cleanly as its native.png/.jpg/.webp/.giffile inspillDirand replaced with a compact text notice + path/dimensions/SHA-256, while compliant<= 2000pximages stay inline.Downscaling inside upstream screenshot servers is definitely ideal when you control the server —
--max-image-dim 2000(or1568) gives you a drop-in safety net for third-party servers you can't edit.One detail for the default: the 2000px cap only applies once a request has more than 20 images. Below that, Anthropic accepts up to 8000px a side, so with --max-image-dim 2000 a short session spills images it could have kept inline. Counting the images in context before picking the limit would spill less.
Great point on the two-tier API rule (
<=20images allows up to8000px,21+enforces2000px). In a live stdio proxy wrapped around a single MCP server, there are two traps with dynamically relaxing the cap on the first 20 images:messages[]transcript. Ifmcp-dietlets a3200pxscreenshot pass inline as image#1and only switches to2000pxafter image#20, a totally compliant1280x720image#21still locks up the session because Anthropic re-validates every image still in conversation history against the2000pxceiling.Since Anthropic downscales anything past ~1568px/2576px anyway, keeping
--max-image-dim 2000as the session-safe default avoids delayed turn-21 lockups without throwing away useful resolution; and for genuinely short<=20-image sessions, you can opt in to--max-image-dim 8000(documented in@framy2/mcp-diet@0.3.1).The cache-invalidation multiplier is usually worse than the raw 20,000-token schema weight on turn one. Once tools[] order drifts mid-session, the miss forces a full cache rewrite across every trailing system and message block on that request, so minor MCP list jitter compounds across long threads.
Spilling >= 512 KiB tool outputs to disk also trades one failure mode for another unless the preview carries clear structure. Replacing an 8 MiB pipe crash with a compact summary keeps the Claude Code transport alive, yet the agent will burn follow-up turns reading chunks of that temp file if the preview omits byte offsets or section headers.
Separating zero-cost CI contract checks in agent-wire-tap from live passthrough tracing catches drifted prefixes before any API spend starts.
Spot-on on both points — thank you for calling out the blind-paging trap on spilled payloads.
Based directly on your feedback, we just shipped @framy2/mcp-diet v0.2.0 (
017ed7d, github.com/FramY2/mcp-diet) with two additions inguardToolCallResult:buildSpillStructureMap): When spilling an oversized output, the inline summary now includes total lines/bytes, SHA-256, head/tail previews, and up to 20 structural entries with exact[L<start>-L<end> | bytes <start>..<end>]spans (top-level JSON object keys with array counts, JSON array chunks, or Markdown/log section headings).mcp_diet_read_spillvirtual tool: The proxy injects a read-only,realpathSync-confined reader acceptingstartLine/endLine,offsetBytes/maxBytes, or RFC 6901jsonPointer(/results/0), so the agent jumps straight to the exact slice in one call instead of paging blind.And on the CI side, @framy2/agent-wire-tap v0.3.0 (
d373928, github.com/FramY2/agent-wire-tap) now supports--replay trace.jsonl+--assert-tools-sortedand--assert-no-prefix-divergencefor zero-API-spend prefix verification.Failure mode 3 is the one that bit me hardest — a single reordered tool re-pricing every token in the turn is easy to miss because nothing errors, the bill just quietly grows. One thing I'd add to the fix list: assert on the serialized prefix, not just the config file. Hosts can inject their own tools or re-sort the list between turns, so two runs with an identical .mcp.json can still diverge, and the cache breakpoint has to sit after the whole tool list, host-injected tools included, or the prefix never matches. Deterministic sorting in the proxy helps, but only if nothing downstream reorders it again. Same thinking applies to the disableAllHooks drift: treating settings.json as immutable for the life of a session (and diffing it if it changes) is cheaper than debugging a silently dropped guardrail after the fact.
Thank you — that distinction between static
.mcp.jsonchecks and asserting on the actual serialized wire prefix after host tool injection +cache_controlplacement is huge, as is lockingsettings.jsonagainst mid-sessiondisableAllHooksdrift.We just shipped both fixes across our releases today:
d373928, github.com/FramY2/agent-wire-tap): Added--assert-tools-sorted,--assert-cache-breakpoint-covers-tools(verifying acache_controlbreakpoint sits at or after the last serialized tool block — or top-levelcache_control— catching host-injected tools appended after an existing breakpoint),--assert-no-prefix-divergence, repeatable--assert-layer-hash <layer:hexPrefix>, and offline--replay trace.jsonlfor CI.ctxwise lock --all-agents(locking.claude/settings.json,.claude/settings.local.json,disableAllHooks,.claude/rules/**/*.md, and.mcp.jsonwith secret-redacted JSON hashing) paired with fail-closedctxwise drift --policyreviewed path rules (deny>warn>allow>unmatched).A tool result remains in the history, so an 8 MB response is paid on every turn after it, not only on the turn that crashed. Capping its size where the tool returns costs less than trimming it later. Did the cache miss start right after that result?
Some comments may only be visible to logged-in visitors. Sign in to view all comments.