SDK MCP servers show 'failed' status (v0.1.0 + CLI v2.0.8)

[znaixian]

Bug Report: SDK MCP Servers Show 'failed' Status in Python SDK v0.1.0

Summary

SDK MCP servers created with create_sdk_mcp_server() consistently show status: 'failed' when used with Claude Agent SDK Python v0.1.0 and Claude CLI v2.0.8, even though the server object is created successfully.

Environment

• Python SDK Version: claude-agent-sdk==0.1.0
• Claude CLI Version: 2.0.8 (Claude Code)
• Python Version: 3.10
• OS: Windows 11
• Installation Method: pip install claude-agent-sdk, npm install -g @anthropic-ai/claude-code

Expected Behavior

SDK MCP servers created with create_sdk_mcp_server() should connect successfully and be available to Claude, similar to how subprocess MCP servers work.

Actual Behavior

SDK MCP servers show 'status': 'failed' in the system init message, and Claude reports it doesn't have access to the tools:

'mcp_servers': [{'name': 'math', 'status': 'failed'}]

Claude's response:

"I don't have access to an `add_numbers` tool..."

Reproduction Steps

Minimal Reproducible Example

import anyio
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, query

# Define a simple tool
@tool(
    name="add_numbers",
    description="Add two numbers together",
    input_schema={
        "a": float,
        "b": float
    }
)
async def add_numbers(args):
    result = args["a"] + args["b"]
    return {
        "content": [{
            "type": "text",
            "text": f"{args['a']} + {args['b']} = {result}"
        }]
    }

async def main():
    # Create SDK MCP server
    server = create_sdk_mcp_server(
        name="math-tools",
        version="1.0.0",
        tools=[add_numbers]
    )

    print(f"Server created: {server}")
    # Output: {'type': 'sdk', 'name': 'math-tools', 'instance': <Server object>}

    # Configure options
    options = ClaudeAgentOptions(
        mcp_servers={"math": server}
    )

    # Query Claude
    async for message in query(
        prompt="What is 5 + 3? Use the add_numbers tool.",
        options=options
    ):
        print(message)

anyio.run(main)

Observed Output

SystemMessage(..., 'mcp_servers': [{'name': 'math', 'status': 'failed'}], ...)
AssistantMessage(content=[TextBlock(text="I don't have access to an `add_numbers` tool...")])

Root Cause Analysis

After investigating the SDK source code, I found:

1. SDK creates the server correctly (claude_agent_sdk/_internal/client.py lines 81-87):

   • Extracts SDK MCP servers from options
   • Stores the instance object

2. SDK passes config to CLI (claude_agent_sdk/_internal/transport/subprocess_cli.py lines 139-156):

   • Strips the instance field before passing to CLI
   • Passes {'type': 'sdk', 'name': 'math-tools'} via --mcp-config

3. CLI doesn't recognize 'type': 'sdk':

   • Claude CLI v2.0.8 --mcp-config expects file paths or subprocess configs
   • No support for in-process SDK servers indicated in claude --help

Workaround

Subprocess MCP servers work correctly:

options = ClaudeAgentOptions(
    mcp_servers={
        "my-tools": {
            "command": "python",
            "args": ["path/to/mcp_server.py"]
        }
    }
)

This produces:

'mcp_servers': [{'name': 'my-tools', 'status': 'connected'}]

Comparison: What Works vs What Doesn't

Method	Status	Note
Subprocess MCP (command/args)	✅ connected	Works perfectly
SDK MCP (create_sdk_mcp_server)	❌ failed	Doesn't work

Question

Is SDK MCP server support planned for a future CLI release, or is there a CLI flag/version that supports it? The Python SDK v0.1.0 has all the code for SDK MCP servers, but the CLI appears to not recognize them.

Related Issues

• ProcessTransport Error When Using MCP Servers #176 - ProcessTransport Error When Using MCP Servers
• [BUG] Claude Code SDK: SDK MCP server faills to connect due to closed stream claude-code#6710 - SDK MCP server fails to connect due to closed stream

Additional Context

The documentation and SDK code suggest SDK MCP servers should work for in-process tools, but there appears to be a version mismatch between the Python SDK's capabilities and the CLI's support.

Proposed Solutions

1. Short-term: Document that SDK MCP servers require a specific CLI version
2. Medium-term: Add CLI support for 'type': 'sdk' MCP servers
3. Long-term: Ensure SDK and CLI versions are synchronized on feature support

---

Thank you for the excellent SDK! Subprocess MCP works great - just wanted to report this incompatibility for in-process SDK servers.

[ujitkumar1]

Yes, I'm also facing the same issue

[dltn]

String prompts can't be used with SDK MCP servers. If you change to AsyncIterable[dict[str, Any]], this should work (see examples/mcp_calculator.py).

We're working on updated interfaces to make this easier to use – stay tuned!

Better error messaging: #207

[mattppal]

Had the same issue, thanks for the heads up @dltn

---

To be a bit more clear for other readers, the solution is to ClaudeSDKClient over query, as query does not support custom tools (in-process MCP servers)

This is mentioned in the comparison table here, though it's easy to miss

The mcp_calculator example is a good demonstration of using ClaudeSDKClient

[v-raja]

@dltn this is closed, but the docs should be updated to clearly mention this. Claude code should be able to read the docs and figure this out, but it wasn't able to. Thanks for the great work on cc!