[DOCS] Agent SDK MCP docs omit immediate connection behavior for initialize-registered servers

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-sdk/mcp

Section/Topic

The SDK MCP servers section, the mcpServers configuration guidance, and the TypeScript SDK reference for dynamically changing MCP servers.

Current Documentation

The Agent SDK MCP guide says:

You can configure MCP servers in code when calling query(), or in a .mcp.json file loaded via settingSources.

Under SDK MCP servers, it says:

Define custom tools directly in your application code instead of running a separate server process. See the custom tools guide for implementation details.

The custom-tools guide explains the normal registration path as:

Pass the MCP server you created to query via the mcpServers option.

The TypeScript reference also lists setMcpServers() as a query method and describes it only as:

Dynamically replace the set of MCP servers for this session. Returns info about which servers were added, removed, and any errors

What's Wrong or Missing?

Claude Code v2.1.210 fixed SDK MCP servers registered through an initialize control request so they start connecting immediately instead of waiting until the next turn. The current documentation describes initial query() configuration and exposes both initialization methods and setMcpServers(), but it does not document the initialize control-request registration path or when servers added through it begin connecting.

An SDK integration that registers an in-process MCP server through the control channel therefore cannot tell from the documentation whether the server is ready for the current turn, whether the first turn can observe its tools, or whether the application must send another turn or explicitly wait for a status change. This makes the v2.1.210 behavior change and the expected first-turn semantics undiscoverable.

Suggested Improvement

Expand the Agent SDK MCP and TypeScript reference documentation to cover runtime MCP registration through an initialize control request. Document the request shape or the supported SDK method that produces it, explain that SDK MCP servers begin connecting immediately as of Claude Code v2.1.210, and state when their tools become available to the current turn.

Add a concise TypeScript and Python example showing a server registered after session startup, how to observe its connection status, and how to handle connection errors before calling one of its tools. Clarify how this path relates to query()'s initial mcpServers option and setMcpServers().

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/agent-sdk/mcp | 73-80, 330-332 | SDK MCP configuration and server registration paths |
| https://code.claude.com/docs/en/agent-sdk/custom-tools | 131-135 | Passing an in-process SDK MCP server to query() |
| https://code.claude.com/docs/en/agent-sdk/typescript | 487-537 | Query control methods, setMcpServers(), and initialization behavior |

Total scope: 3 pages affected

The behavior change is documented in the Claude Code v2.1.210 changelog. The existing MCP guide explains that the SDK reports server status in the system init message, but it does not explain the status or turn-availability sequence for servers registered later through an initialize control request.