[DOCS] MCP docs omit multi-block error content guidance for server authors

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

For MCP server authors and nearby MCP server output/error handling guidance

Current Documentation

The MCP page currently limits Claude Code's MCP server-author guidance to server instructions and output-size limits:

If you're building an MCP server, the server instructions field becomes more useful with Tool Search enabled. Server instructions help Claude understand when to search for your tools, similar to how skills work. Add clear, descriptive server instructions that explain: What category of tasks your tools handle When Claude should search for your tools * Key capabilities your server provides Claude Code truncates tool descriptions and server instructions at 2KB each. Keep them concise to avoid truncation, and put critical details near the start.

And the same page only discusses MCP output limits in terms of size warnings:

When MCP tools produce large outputs, Claude Code helps manage the token usage to prevent overwhelming your conversation context: Output warning threshold: Claude Code displays a warning when any MCP tool output exceeds 10,000 tokens Configurable limit: You can adjust the maximum allowed MCP output tokens using the MAX_MCP_OUTPUT_TOKENS environment variable * Default limit: The default maximum is 25,000 tokens

No current Claude Code page explains how MCP error payloads are represented or that an error can contain multiple content blocks.

What's Wrong or Missing?

Changelog v2.1.89 says:

Fixed MCP tool errors truncating to only the first content block when the server returns multi-element error content

That changelog entry exposes a Claude Code behavior that the docs do not currently explain for MCP server authors: an MCP error result can include multi-element content, and Claude Code now preserves the full error payload instead of surfacing only the first block.

Right now the Claude Code docs do not tell server authors:

1. that MCP error results can contain multiple content blocks,
2. that Claude Code is expected to surface the full error content array,
3. where to look for the Claude Code-facing contract versus the generic MCP/API schema.

Without that guidance, rich MCP error responses are hard to design and hard to debug in Claude Code.

Suggested Improvement

Add a short subsection to https://code.claude.com/docs/en/mcp near For MCP server authors that explains how Claude Code handles MCP tool error payloads.

It should:

• state that MCP error results may return content as multiple blocks, not just a single string,
• clarify that Claude Code surfaces the full error content array,
• include a minimal example such as:

{
"is_error": true,
"content": [
{ "type": "text", "text": "Validation failed" },
{ "type": "text", "text": "Missing required field: project_id" }
]
}

• link to the detailed platform schema pages for the full set of supported block types.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary Claude Code MCP page; current server-author guidance omits rich error content behavior |
| https://platform.claude.com/docs/en/agents-and-tools/mcp-connector | Agent SDK cross-reference showing mcp_tool_result with is_error and a content array |
| https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls | Generic tool_result docs say content may be a list of nested content blocks and is_error can be true |
| https://platform.claude.com/docs/en/agent-sdk/typescript | CallToolResult defines MCP tool results as content arrays with optional isError |

Total scope: 4 pages affected

Source: Changelog v2.1.89

Exact changelog entry:

Fixed MCP tool errors truncating to only the first content block when the server returns multi-element error content