Claude Code Shipped CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH on Sept 22. It Fixes One of the Four Things Three Bug Reports Asked For (2026)

Claude Code v2.1.280, released September 22, 2026, added an environment variable most changelogs would bury in a single line: CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH, which lets you raise the hard-coded 2,048-character cap that Claude Code has silently applied to every MCP tool description and server instructions field since v2.1.84. That cap has its own paper trail — three separate GitHub issues, six months apart, each closed by the stale-bot with no maintainer reply. The most detailed one asked for four specific fixes. Sept 22 shipped one of them.

If you write or run MCP servers, the gap between “shipped a fix” and “shipped the fix that was asked for” matters, because the two problems this cap actually caused — the AI hallucinating tool arguments and you having no way to notice why — aren’t the same problem, and only one of them is solved by an environment variable.

The Three-Issue Paper Trail

• #41593 (opened March 31, 2026, closed as stale May 6) reported the cap first. A code_executor MCP tool embedded ~60 browser automation function signatures in its description — 9,336 characters. After truncation, only 15 of 60 survived alphabetically (addInitScript through getBoundingBox); core functions like pageNavigate and takeSnapshot were invisible past the cut. The model hallucinated Playwright-style function names that didn’t exist in the sandbox. The author’s workaround was binary-patching the constant (WoH=2048 → WoH=15e3) after every Claude Code update.
• #81268 (opened July 26, closed as stale September 9) reformulated the ask entirely: it deliberately did not ask to raise the limit, arguing truncation is a reasonable policy for strings that enter every request’s system prompt. It asked instead for the truncation to be observable. Server instructions truncation already logged a debug line ("Server instructions truncated from 9029 to 2048 chars"); tool description truncation logged nothing, anywhere. Worse, the /mcp UI showed the author’s full, untruncated description — so the one place a server author could check their work showed them text the model never received. One commenter reported 502 truncation events across their own MCP logs, the worst case losing 81% of a 10,780-character instructions field.
• #87650 (opened August 18, closed as stale September 21 — one day before the fix shipped) added a controlled same-day comparison: the same MCP server’s tool description reached claude.ai complete at 16,275 characters, but reached Claude Code truncated to 2,061 (2,048 plus a "… [truncated]" marker) — 12.7% of the original. It also documented a sharper failure mode than either prior report: the surviving 2,048-character prefix of a TypeScript interface listing six parameters looked like a complete, closed spec, when two of those parameters were in fact documented only past the cut. The model had no signal the interface it was reading was incomplete, so it called the tool with a narrower, wrong shape.

#87650 closed its report with four explicit, ranked requests. That ranking is the whole story of what shipped and what didn’t.

What v2.1.280 Actually Shipped

One line, from the release notes:

Added CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH to change the 2,048-character cap on MCP tool descriptions and server instructions for every MCP server in the session

Usage is exactly what it sounds like — set it before starting a session, or in your shell profile, or under env in .claude/settings.json:

export CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH=8192

Note the scope: “for every MCP server in the session.” This is a session-wide ceiling, not a per-tool or per-server override. If one of your MCP servers has a code_executor tool that legitimately needs 9,000 characters to enumerate 60 function signatures, and another has a two-line search tool, raising the variable to fit the first one raises the budget for both — there’s no way to set a smaller cap for the servers that don’t need it, and no documented maximum for how high you can set it before something else (context budget, a client-side buffer) pushes back.

Four Requests, One Shipped

#87650 ranked its asks in order of implementation cost, cheapest first. Here’s where each one stands as of v2.1.280:

The request that shipped was explicitly the one marked “alternatively/additionally” in the original report — the fallback, not the primary ask. The two changes #81268 called the highest-value, lowest-cost fixes (logging and UI accuracy) are the two that didn’t move. If your actual problem was #41593 and #87650’s problem — a tool description that’s too long and gets cut — you’re covered now. If it was #81268’s problem — you don’t know your description is being cut at all, because nothing tells you — v2.1.280 doesn’t change that. You can now raise the ceiling, but you still won’t get a log line or an accurate /mcp view telling you when you’ve hit it.

The Docs Haven’t Caught Up Yet

As of this writing, CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH does not appear on the official environment variables reference — the page that documents every other Claude Code environment variable, including MCP-adjacent ones like CLAUDE_AGENT_SDK_MCP_NO_PREFIX. It isn’t on the MCP setup page either, which does document a related but separate limit: MAX_MCP_OUTPUT_TOKENS, a 10,000-token warning threshold on tool output (what a tool call returns), not tool description (what the model is told about the tool before it’s called). It’s an easy pair to confuse if you’re skimming for “the MCP length setting” — they cap different things, and only one of the two currently has a documented row.

This is the same pattern The Prompt Shelf has flagged with other September 2026 releases: a fix ships in the changelog days before the reference page an operator would actually search catches up. If you go looking for this variable in the docs right now, you won’t find it — the changelog entry is, for the moment, the only place it’s written down.

If You Maintain an MCP Server

Setting the environment variable only helps if you control the Claude Code session that connects to your server — most server authors don’t, since it’s the caller’s shell or settings.json, not anything the server itself can declare. Until a per-tool _meta override ships, three things actually work from the server side:

1. Fit descriptions and instructions under 2,048 characters by construction. One commenter on #81268 described gating at an 1,800-character safe threshold with margin for wording tweaks, logging anything over that on their own side before Claude Code ever sees it — since Claude Code’s own description truncation still produces no log to catch it downstream.
2. Route content that must arrive whole through notifications/claude/channel. Per #81268’s investigation, the params.content field of that notification type is not subject to the 2,048-character cap — it was, at the time, the only automatic path into a session’s context with no length limit. A peer profile or protocol document too large for instructions can go there instead.
3. If you do control the calling environment — your own CI, a wrapped CLI, a documented setup script for users — set CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH there explicitly rather than assuming users will discover and set it themselves, since it isn’t in the docs yet for them to find.

FAQ

Does CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH apply per MCP server or per tool? Per session. Per the v2.1.280 release notes, it changes the cap “for every MCP server in the session” — there’s no per-tool or per-server override, so raising it for one verbose tool raises it for all connected servers.

Does this fix mean Claude Code now logs when a tool description gets truncated? No. As of v2.1.280, tool description truncation still produces no log line, unlike server instructions truncation, which has logged a debug message since before this change. That gap was one of the explicit requests in issue #87650 and remains open.

Will the /mcp command now show me the truncated text the model actually receives? No. /mcp continues to display the full, untruncated description an author wrote — not the version assembled into the model’s context after the cap is applied. This mismatch is documented in issues #81268 and #87650 and wasn’t addressed in this release.

What’s the difference between MAX_MCP_OUTPUT_TOKENS and CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH? MAX_MCP_OUTPUT_TOKENS caps how many tokens a tool’s result can return before Claude Code warns about it (10,000 by default). CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH caps how many characters a tool’s description or a server’s instructions can use before the model even calls it (2,048 by default). They govern different parts of the MCP request lifecycle and are set independently.

Related Reading

• .mcp.json Configuration Reference: Complete Guide for Claude Code MCP Setup
• Writing Your Own MCP Server for Claude Code: A Practical Guide
• How to Test and Debug MCP Servers for Claude Code
• Claude Code v2.1.273 Added 5 New Gateway Headers. The Official Protocol Docs Don’t List Them Yet

Browse real-world .mcp.json and settings.json patterns in our gallery.