Follow Discord
Sweep 22 Oct 2026 · 04:32Z Build v2.1.308 527 read Stable v2.1.308 Latest v2.1.308 Next v2.1.308 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Code CLI 27 Aug 2026
One change · claude-code

Connect to external tools with MCP changedagent-sdk/mcp

Nearest release: v2.1.248, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here
Lines+15added
Lines−3removed
From line 142 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits21to this page, all time

The whole hunk

from line 142, old and new numbered
/
lines
from line 142
142142 
143143## Connection timing
144144 
145Claude Code registers the servers you pass in `options.mcpServers` at startup and emits the [init message](#error-handling) once the first-turn wait, if any, resolves. Servers loaded from [settings files](#from-a-config-file) such as `.mcp.json` don't get the full wait and commonly show `pending` at init. When each `options.mcpServers` server connects, and whether it delays the first turn, depends on its type:
145Claude Code registers the servers you pass in `options.mcpServers` at startup and emits the [init message](#error-handling) once the first-turn wait, if any, resolves. Without `options.mcpServers`, Claude Code waits 2 seconds for pending servers before the first turn, so servers loaded from [settings files](#from-a-config-file) such as `.mcp.json` commonly show `pending` at init. When each `options.mcpServers` server connects, and whether it delays the first turn, depends on its type:
146146 
147147| Server type | Delays the first turn? | First-turn wait timeout |
148148| :------------------------------------------------------------------------------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------ |
from line 699
699699 
700700MCP servers can fail to connect for various reasons: the server process might not be installed, credentials might be invalid, or a remote server might be unreachable.
701701 
702Claude Code emits a `system` message with subtype `init` at the start of each query. This message includes the connection status for each MCP server. The `status` field can be `"pending"`, `"connected"`, `"failed"`, `"needs-auth"`, or `"disabled"`. Claude Code emits the init message after the [first-turn connection wait](#connection-timing) for servers passed in `options.mcpServers`, so such a server that connected within the wait shows `"connected"`. A `"pending"` status means the server hasn't connected yet, which is common for [settings-file servers](#from-a-config-file) that don't get the full wait, or that its tool list was [served from the cache](#connection-timing) with a connection made on first use; the reported status for a deadline-expired server can be `"pending"` or `"failed"` depending on timing. Don't treat `"pending"` as a failure. Check for `"failed"` or `"needs-auth"` to detect servers that won't be usable:
702Claude Code emits a `system` message with subtype `init` at the start of each query. This message includes the connection status for each MCP server. The `status` field can be `"pending"`, `"connected"`, `"failed"`, `"needs-auth"`, or `"disabled"`. Claude Code emits the init message after the [first-turn connection wait](#connection-timing) for servers passed in `options.mcpServers`, so such a server that connected within the wait shows `"connected"`.
703703 
704In the init message, don't treat `"pending"` as a failure on its own. It can mean any of these:
705 
706* The server hasn't connected yet. See [how long Claude Code waits for it before the first turn](#connection-timing)
707* The server's tool list was [served from the cache](#connection-timing), with a connection made on first use
708* The connection deadline expired. Such a server reports `"pending"` or `"failed"` depending on timing
709 
710Check for `"failed"` or `"needs-auth"` to detect servers that won't be usable:
711 
704712<CodeGroup>
705713 ```typescript TypeScript theme={null}
706714 import { query } from "@anthropic-ai/claude-agent-sdk";
from line 788
780788 ```
781789</CodeGroup>
782790 
791A remote server's status can also change after it reports `"connected"`. When the connection to it drops mid-session, Claude Code moves the server back to `"pending"` while [reconnecting](/docs/en/mcp#automatic-reconnection). A later `mcpServerStatus()` call in TypeScript, or [`ClaudeSDKClient.get_mcp_status()`](/docs/en/agent-sdk/python#methods) in Python, can then report `"pending"` for a server you saw connected earlier, with no configuration change on your side.
792 
793After five reconnection attempts fail, the server reports `"failed"`, or `"needs-auth"` when it needs authorizing again. To retry manually, call [`reconnectMcpServer()`](/docs/en/agent-sdk/typescript#methods) in TypeScript or [`ClaudeSDKClient.reconnect_mcp_server()`](/docs/en/agent-sdk/python#methods) in Python.
794 
783795## Troubleshooting
784796 
785797### Server shows "failed" status
from line 817
805817 ```
806818</CodeGroup>
807819 
808A `"pending"` status doesn't mean the server failed; see [Error handling](#error-handling) for the two cases it covers at init. To get updated statuses later in the session, call the query's `mcpServerStatus()` method in the TypeScript SDK, or [`ClaudeSDKClient.get_mcp_status()`](/docs/en/agent-sdk/python#methods) in Python.
820A `"pending"` status doesn't mean the server failed. See [Error handling](#error-handling) for the cases it covers at init. To get updated statuses later in the session, call the query's `mcpServerStatus()` method in the TypeScript SDK, or [`ClaudeSDKClient.get_mcp_status()`](/docs/en/agent-sdk/python#methods) in Python.
809821 
810822Common causes:
811823 
Feedback