[BUG] MCP client silently drops all tools when third-party server includes outputSchema in tools/list response

Preflight Checklist

I have searched existing issues and this hasn't been reported yet
This is a single bug report (please file separate reports for different bugs)
I am using the latest version of Claude Code

What's Wrong?

When a third-party MCP server (not claude mcp serve) includes outputSchema, title, or toolAnnotations fields in its tools/list response — as defined by the MCP 2025-11-25 specification — Claude Code's MCP client silently fails to register all tools from that server.

The MCP server shows as connected (resources via ListMcpResourcesTool and ReadMcpResourceTool work correctly), but zero tools appear in Claude Code's tool list. There are no error messages visible to the user.

This differs from existing reports (#24742, #10031) which are about claude mcp serve acting as a server. This bug is about Claude Code acting as an MCP client consuming a third-party server.

What Should Happen?

Claude Code should either:

Parse and use the outputSchema, title, and toolAnnotations fields from MCP 2025-11-25, or
Gracefully ignore unknown/unsupported fields and still register the tools

Error Messages/Logs

No error messages are shown to the user. The tools simply do not appear.
MCP resources from the same server work fine — only tools are affected.

Steps to Reproduce

Create an MCP server (any language/SDK) that registers tools with outputSchema in the tools/list response. For example, using the Kotlin MCP SDK 0.8.3:

server.addTool(
    name = "query_container",
    description = "Query containers",
    inputSchema = myInputSchema,
    title = "Query Container",                    // MCP 2025-11-25
    outputSchema = ToolSchema(buildJsonObject {    // MCP 2025-11-25
        put("type", "object")
        put("description", "Response data")
    }),
    toolAnnotations = ToolAnnotations(             // MCP 2025-11-25
        readOnlyHint = true,
        destructiveHint = false,
        idempotentHint = true,
        openWorldHint = false
    )
) { request -> /* handler */ }

Configure Claude Code to connect to this MCP server (via stdio or Docker)
Start Claude Code — the server connects successfully
ListMcpResourcesTool returns resources from the server (confirming connection)
No MCP tools from this server appear in Claude Code's available tools
Comment out title, outputSchema, and toolAnnotations from the addTool() call
Rebuild and restart
All tools now appear and work correctly

Claude Model

Opus

Is this a regression?

I don't know

Claude Code Version

2.1.38

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

Windows Terminal

Additional Information

Server details: Kotlin-based MCP server using io.modelcontextprotocol:kotlin-sdk:0.8.3, running in Docker via stdio transport. The server registers 13 tools and 18 resources.

Narrowing the cause: The issue is specifically in the tools/list response parsing — when the same server omits outputSchema, title, and toolAnnotations from tool registration (but keeps everything else identical, including structuredContent in CallToolResult responses), all 13 tools appear and work correctly.

Workaround: Comment out outputSchema, title, and toolAnnotations in the server's tool registration. structuredContent in tool responses can remain enabled without issue.

Related issues:

[BUG] mcp serve: tools advertise outputSchema but return no structuredContent #24742 — outputSchema advertised but structuredContent null (about claude mcp serve, not third-party servers)
[BUG] claude mcp serve tools not displayed in MCP clients due to missing type field in outputSchema #10031 — outputSchema missing type field breaks tool display (closed, fixed for claude mcp serve)
[BUG] "MCP Tools Not Available in Conversation Interface Despite Successful Connection" #2682 — MCP tools not available despite connection (may be same root cause for some reporters)

Found 3 possible duplicate issues:

[BUG] "MCP Tools Not Available in Conversation Interface Despite Successful Connection" #2682
MCP server connects with hasTools:true but tool not available via ToolSearch or direct invocation #24899
[BUG] MCP servers connect successfully but tools are not exposed to assistant #12164

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Additional Findings: `instructions`, `annotations`, `execution`, and extra capabilities also trigger silent tool drop

We independently reproduced this exact symptom with XcodeBuildMCP v2.0.7 (MCP SDK v1.26.0) on Claude Code 2.1.39 (macOS, Darwin 24.6.0).

Root Cause (broader than `outputSchema`)

Claude Code's MCP client silently drops all tools from a server when the tools/list or initialize responses contain fields it doesn't expect. Through systematic testing, we identified these fields as triggers:

In initialize response:

instructions field (large string with server documentation)
capabilities.tools.listChanged: true
capabilities.resources (subscribe, listChanged)
capabilities.logging

In tools/list response (per-tool):

execution (e.g. {"taskSupport": "forbidden"})
annotations (with non-standard title property inside)
inputSchema.$schema (JSON Schema metadata)

How We Confirmed

Canary test: Created a minimal 1-tool MCP server returning bare {name, description, inputSchema} with capabilities: {tools: {}} — tools loaded successfully ✅
XcodeBuildMCP proxy (stripping only execution): Tools still dropped ❌
Proxy stripping execution + annotations + $schema): Tools still dropped ❌
Proxy also cleaning initialize response (removing instructions, simplifying capabilities to {tools: {}}): Tools loaded ✅

Impact

This affects any MCP server using @modelcontextprotocol/sdk >= 1.26.0, which automatically adds instructions, annotations, execution, and richer capabilities. XcodeBuildMCP is a popular server (iOS/macOS development) and its tools are completely invisible in Claude Code despite showing as "Connected" in claude mcp list.

Workaround

We wrote a Node.js proxy that sits between Claude Code and XcodeBuildMCP, stripping problematic fields from both the initialize and tools/list responses:

// In initialize response:
delete msg.result.instructions;
msg.result.capabilities = { tools: {} };

// In tools/list response:
const { execution, annotations, ...rest } = tool;
delete rest.inputSchema['$schema'];

Full proxy: https://gist.github.com/ (happy to share if useful)

Expected Behavior

Claude Code should gracefully ignore unknown fields in MCP responses per the MCP spec's extensibility model, rather than silently dropping all tools.

Environment

Claude Code: 2.1.39
XcodeBuildMCP: 2.0.7
@modelcontextprotocol/sdk: 1.26.0
macOS: Darwin 24.6.0 (Apple Silicon)
Node.js: v23.x

fix: disable MCP 2025-11-25 tool registration fields that break Claud…

release: v2.0.2 — README and doc corrections (#34)

Still hitting this on Claude Code Opus 4.6 and claude-code 2.1.63 on macOS. My MCP server correctly negotiates the protocol version and only includes outputSchema when 2025-11-25 is the agreed version, but Claude Code silently drops all tools. The server appears connected with zero tools available.

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Navigation Menu

Repository navigation

[BUG] MCP client silently drops all tools when third-party server includes outputSchema in tools/list response #25081

Preflight Checklist

What's Wrong?

What Should Happen?

Error Messages/Logs

Steps to Reproduce

Claude Model

Is this a regression?

Claude Code Version

Platform

Operating System

Terminal/Shell

Additional Information

Additional Findings: `instructions`, `annotations`, `execution`, and extra capabilities also trigger silent tool drop

Root Cause (broader than `outputSchema`)

How We Confirmed

Impact

Workaround

Expected Behavior

Environment

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[BUG] MCP client silently drops all tools when third-party server includes outputSchema in tools/list response #25081

Description

Preflight Checklist

What's Wrong?

What Should Happen?

Error Messages/Logs

Steps to Reproduce

Claude Model

Is this a regression?

Claude Code Version

Platform

Operating System

Terminal/Shell

Additional Information

Activity

github-actions commented on Feb 11, 2026

greenstevester commented on Feb 12, 2026

Additional Findings: instructions, annotations, execution, and extra capabilities also trigger silent tool drop

Root Cause (broader than outputSchema)

How We Confirmed

Impact

Workaround

Expected Behavior

Environment

brandonbloom commented on Mar 3, 2026

github-actions commented on Mar 31, 2026

github-actions commented on Apr 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Additional Findings: `instructions`, `annotations`, `execution`, and extra capabilities also trigger silent tool drop

Root Cause (broader than `outputSchema`)