Claude Code MCP Context Overload: Diagnose Tool Load and Large Results

If MCP is crowding out useful work in Claude Code, first identify when the context grows. Pressure before a call suggests tool loading or other startup material. A jump after a call points toward its result. Growth across retries points toward accumulated conversation history. Each needs a different fix; counting configured servers will not tell you which one to use.

Start with /context all, then inspect the last tool result and the server's status. Keep the access needed for your task, change one relevant setting or output request, and compare the same task again. Success means Claude can still reach the needed evidence and finish the job, with less irrelevant material to carry forward.

The behavior described here reflects documentation checked on October 6, 2026. The examples below use synthetic deployment logs; they are output-design examples, not measurements of Claude's tokens, speed, or billing.

Context Budget Ledger

Record a baseline before changing the setup. Claude Code's context documentation explains that instructions, loaded files, tool outputs, and startup material share the working window. Its capacity depends on the model and route. Use your session's displayed figures rather than an assumed 200K limit or a screenshot from someone else's setup.

Your ledger can be a few notes alongside the task:

Do not use response latency alone as a context measurement. A slow connection, an authorization failure, and a large successful result can all interrupt work, but changing the result shape only addresses the last of those.

For example, suppose your task is to explain why checkout deployment d42 failed. You need the relevant time range, counts for each failure type, and evidence identifying what to fix. A dump of every service's logs is unnecessary. A response containing only “four failures” is also insufficient: it hides whether those failures share a cause.

That gives you an acceptance test before cleanup: retain the failure counts, preserve each distinct error type, and make the supporting records retrievable. You can now judge a smaller response by what it lets you do.

Check Tool Search when load appears before calls

On supported paths, unset ENABLE_TOOL_SEARCH defers definitions; names and server instructions still load. Explicit auto uses 10%; auto:N sets 0–100%; false loads upfront. alwaysLoad overrides deferral. Non-first-party ANTHROPIC_BASE_URL defaults search off; true requires working tool_reference support. Google Agent Platform 4.5+ defaults on after v2.1.221; older generations cannot force it. Foundry deployments that reject it, experimental-beta disabling, and managed policy also constrain support. See Claude Code's current Tool Search conditions.

Treat those conditions as a compatibility check before choosing a mode. In particular, unset and auto are different configurations. Applying an old “10% default” recommendation can change the behavior you were trying to inspect.

For an existing installation, work through these questions:

1. What is actually heavy? If files or earlier messages dominate the ledger, changing discovery is unlikely to be the first useful intervention.
2. Does this provider and model path support discovery? Record the client version and route you are using. A variable cannot make an incompatible proxy accept a request.
3. Is upfront loading intentional? A server that must remain immediately available may have an exemption. Decide whether that requirement still applies to this task before changing it.
4. Can the required tool still be found and used? Ask for one narrow, meaningful read through the integration. Finding its name is only an intermediate check.

If an explicit override makes requests fail, restore the previous setting and investigate compatibility. Avoid stacking several environment or configuration changes: you would lose the ability to identify which one caused the failure.

If definitions are already deferred but the session balloons after a log search, move to the result budget. Discovery does not decide which log records your investigation needs.

A missing tool needs a status check, not a context purge

In /mcp, distinguish disabled, connecting, authorization-required, and blocked states. Its project toggle retains configuration; newly connected tools can appear on subsequent requests.

Use the state to choose the next action. A deliberately disabled server needs to be re-enabled if the task requires it. An authorization problem needs the applicable access procedure. A connected server whose expected tool cannot be discovered needs a tool-availability check. None of those observations alone establishes context overload.

For reversible cleanup, write down the currently enabled set and the access each task needs. In the deployment example, keep the log integration. If an unrelated design integration is enabled, toggle that one off and repeat the checkout investigation. Restore it when its work resumes, or immediately if the test exposes a dependency you missed.

Keep the changes small enough to explain. “This integration is unused during log diagnosis” is a useful reason to disable it temporarily. “I must get below five servers” is not a testable reason. A skill can provide an investigation method, but it cannot supply external records that the remaining tools cannot access.

Avoid permanently deleting server configuration during the first pass. Preserve the ability to restore the workflow, and verify an actual useful result before calling the cleanup successful.

Large MCP results: persistence is not the same as truncation

The MCP output rules warn above 10,000 tokens; MAX_MCP_OUTPUT_TOKENS defaults to 25,000. Oversized successful foreground text without images is persisted with a file reference; 50,000 characters independently triggers persistence. Error text above roughly 11,000 characters retains the first/last 5,000. Images remain token-limited. Tool _meta["anthropic/maxResultSizeChars"] replaces the character threshold, independently of tokens.

Identify which result you received before deciding that evidence disappeared. A successful text result pointing to a file offers a different recovery path from an error whose middle was omitted. For the file case, locate the relevant section or record and read that portion. For the error case, obtain the missing diagnostic evidence through a narrower request if the integration supports it.

Raising a cap can expose evidence you need, but it is not a footprint reduction. Nor is printing the entire saved file back into the conversation. The useful question is: which part of this result changes the next decision?

For the checkout investigation, ask for a bounded response along these lines:

For checkout deployment d42, inspect the fixed incident time range.
Return the total failed requests, counts by error code, and one record
for each distinct error code. Include record IDs and timestamps.
State the filter and whether results are incomplete. Offer a cursor
or a detail lookup for additional evidence; omit successful requests.

This is a request to use capabilities the server already exposes, not a way to add filters to an arbitrary tool. If its only operation returns every log line, the durable fix belongs in the server's output design.

Design a smaller result that still explains the failure

For a server you control, separate the question from the dataset. The checkout task needs a failure breakdown and traceable examples. Design the initial response around that answer, with an explicit route to the rest of the evidence.

Anthropic's code execution with MCP discussion describes filtering and processing data before it reaches the model. That is a useful design principle here. If you introduce a code-execution environment, sandboxing, resource limits, and monitoring are separate implementation responsibilities; a smaller result alone does not provide them.

A practical pair of operations would be:

Here is a possible preview for a synthetic dataset with four failures:

{
  "scope": {
    "service": "checkout",
    "deployment": "d42",
    "from": "2026-10-06T09:00:00Z",
    "to": "2026-10-06T09:10:00Z"
  },
  "snapshotId": "example-snapshot",
  "totalMatching": 4,
  "countsByCode": {"TIMEOUT": 3, "SIGNATURE_MISMATCH": 1},
  "examples": [
    {"id": "r007", "code": "TIMEOUT", "timestamp": "2026-10-06T09:00:00Z"},
    {"id": "r010", "code": "SIGNATURE_MISMATCH", "timestamp": "2026-10-06T09:03:00Z"}
  ],
  "completeCounts": true,
  "allRecordsIncluded": false
}

The rare signature error survives even if timeouts dominate. The counts describe the full filtered snapshot; the examples are intentionally selective. A reader can ask for r010 before deciding that every failure needs a timeout fix.

These fields are an application design. The MCP 2025-11-25 tools specification allows structured results, output schemas, and resource links, but does not mandate this summary format. Its tools/list cursor paginates tool definitions, not rows returned by your application. JSON may also be duplicated in text content, so choosing structuredContent alone does not ensure compactness.

Implement row pagination against a stable snapshot, with deterministic ordering and a cursor bound to the caller and filter. Otherwise, incoming logs can shift offsets between calls, causing missing or duplicated records. Report partial scans, timeouts, or retention gaps explicitly; a count from an incomplete scan must not masquerade as a complete count.

For a saved export, return a handle that the intended client can actually resolve under the same authorization. A file:// path on a remote server is not sufficient by itself. Include enough information to identify the export's scope, then let the caller retrieve a relevant slice. Keep sensitive or unrelated fields out of the preview, while retaining the diagnostic evidence the task requires.

Check coverage with a local synthetic fixture

The following standalone Python example checks the preview logic and traversal of a fixed list. Run it locally with Python 3 if you want to adapt the design. It does not connect to MCP or Claude; the integer cursor is only an offline stand-in for the bound cursor described above.

import json
from collections import Counter

failure_codes = {
    3: "TIMEOUT", 7: "TIMEOUT", 10: "SIGNATURE_MISMATCH", 11: "TIMEOUT"
}
rows = [
    {
        "id": f"r{i:03d}",
        "service": "checkout",
        "deployment": "d42",
        "timestamp": f"2026-10-06T09:0{i % 7}:00Z",
        "code": failure_codes.get(i, "OK"),
        "detail": "synthetic detail " * 40,
    }
    for i in range(120)
]
failed = sorted(
    (row for row in rows if row["code"] != "OK"),
    key=lambda row: (row["timestamp"], row["id"]),
)
counts = dict(Counter(row["code"] for row in failed))
examples = {}
for row in failed:
    examples.setdefault(row["code"], {
        key: row[key] for key in ("id", "code", "timestamp")
    })
preview = {"totalMatching": len(failed), "countsByCode": counts,
           "examples": list(examples.values())}

cursor, seen = 0, []
while cursor < len(failed):
    page = failed[cursor:cursor + 2]
    seen.extend(row["id"] for row in page)
    cursor += len(page)

assert counts == {"TIMEOUT": 3, "SIGNATURE_MISMATCH": 1}
assert seen == [row["id"] for row in failed]
assert len(seen) == len(set(seen))
assert {row["code"] for row in preview["examples"]} == set(counts)
raw_text = json.dumps(rows, ensure_ascii=False)
preview_text = json.dumps(preview, ensure_ascii=False)
assert len(preview_text) < len(raw_text)
print(json.dumps(preview, indent=2))
print("characters:", len(raw_text), "->", len(preview_text))
print("UTF-8 bytes:", len(raw_text.encode()), "->", len(preview_text.encode()))

The assertions verify this fixture's counts, error-type coverage, and traversal without duplicate IDs. The size comparison measures serialized characters and UTF-8 bytes. Neither number is a token count, and these checks do not establish runtime compatibility or that Claude will make the right diagnosis. Production filtering, authorization, cursor validation, and concurrent updates need their own implementation and tests.

Recover the conversation without repeating the same dump

If the ledger shows accumulated history, save a short checkpoint before recovering the thread. Include the task, fixed evidence scope, findings with record IDs, unresolved questions, required tools, and next action. In the checkout example, keep both error codes and the lookup for r010; discarding that minority case would make the recovery look cleaner while weakening the investigation.

Claude Code's commands reference documents /context all for expanded context details, /compact [instructions] for summarizing the current conversation, and /clear for an empty conversation while project memory remains. Try a focused compaction when useful state exists:

/compact Keep the d42 checkout failure counts, evidence record IDs,
the unresolved signature mismatch, required log access, and next lookup.

Check the resulting summary before proceeding. Compaction is not a guarantee that every important detail survives. If starting a new conversation, carry the checkpoint into it and confirm the required records are still reachable. Do not immediately repeat the broad query that filled the previous thread.

If a single enormous paste leaves too little conversational material to compact, use a saved checkpoint and a fresh conversation rather than retrying the same recovery command indefinitely. A focused subagent can handle future noisy exploration and return findings, but its separate context does not erase material already in the parent. Preserve its needed access and ask for evidence references, not another full dump. See the context behavior documentation.

For broader setup trouble, distinguish two similarly named diagnostics. Current interactive /doctor is a skill that can propose configuration changes requiring confirmation; terminal claude doctor prints installation diagnostics without starting a session. Safe-mode troubleshooting disables customizations for a session, so use it as a broader isolation test rather than evidence that MCP alone caused the problem.

If the issue is a missing persistent instruction or Context7 access rather than catalog or result size, use the guide to diagnosing context, memory, MCP, and Context7.

Verify the cleanup with the same useful task

Return to the acceptance test you wrote before making changes. For checkout deployment d42, the smaller workflow should still identify every failure category, retain trustworthy counts for the chosen interval, and retrieve the record needed to investigate the signature error.

Compare the before-call and after-call ledger using the same service, deployment, time range, and access. For changing live data, use a fixed snapshot or note that the datasets differ. Record whether irrelevant rows were omitted, whether the required tools remained available, and whether another large read was necessary to finish.

If a category disappears or the detail handle fails, repair that loss first. If context still grows after a bounded result, inspect the next call or accumulated history instead of repeatedly tightening the first response. If the task completes and the observed context footprint improves, keep the narrow change and restore integrations needed for other work. There is no universal server count or guaranteed savings percentage.

FAQ

Is an API 529 “server overloaded” error caused by MCP context?

Anthropic's direct API defines 529 overloaded_error as temporary service overload. It is a different failure from an oversized MCP result. Check the status, error type, and request ID; a proxy may phrase the failure differently. Removing tools or compacting a conversation does not establish a remedy for provider overload. See the API error reference.

Should I increase the MCP output limit?

Only when the task needs evidence the current response does not expose. First check whether the result already provides a usable file reference or a detail lookup. A higher limit addresses access to more material; use a narrower query or redesigned result when your goal is to carry less material.

How many MCP servers should I keep enabled?

Keep the integrations required to finish the current workflow and temporarily disable unrelated ones when diagnosing load. Judge the outcome by accessible evidence and completed work. One tool returning an entire dataset can create more trouble than several integrations returning focused answers.

Can I replace MCP with a skill or local script?

A skill can organize the investigation, and a local script can process data you already have. Keep MCP when the task needs external records or actions that those alternatives cannot reach. Moving the analysis elsewhere helps only if the result brought back is focused and sufficiently supported.