Claude Code CLI / MCP Integration
MCP Server Initialization Timeout on Custom Agent Orchestrator
We are integrating a custom MCP server with our Claude Code CLI orchestrator to expose internal APIs. However, the client frequently drops the connection during the handshake phase, citing an initialization timeout. I need to trace the JSON-RPC lifecycle to see where the transport layer is failing.
我们正在将自定义的 MCP 服务器与 Claude Code CLI 编排器集成，以暴露内部 API。然而，客户端在握手阶段频繁断开连接，提示初始化超时。我需要追踪 JSON-RPC 的生命周期，找出传输层失败的具体原因。
The component responsible for coordinating multiple agents, tools, or services.
"The orchestrator routes the query to the appropriate MCP server based on the requested tool schema."
The underlying communication mechanism (e.g., stdio, SSE) for the protocol.
"Switching the transport layer from stdio to SSE resolved our intermittent connection drops."
A stateless, light-weight remote procedure call (RPC) protocol standard used heavily in MCP.
"I dumped the JSON-RPC payloads to standard error to inspect the malformed tool execution request."
To make internal functions, services, or endpoints available to external clients.
"We should only expose read-only database queries through this MCP server for security reasons."
The initial negotiation phase between the client and server to establish a connection.
"The server failed to negotiate capabilities during the initial handshake."
Data, text, or files provided by an MCP server explicitly for the client to read.
"The client successfully subscribed to the log file resource via the MCP protocol."
"The MCP client is hanging during the init phase."
MCP 客户端在初始化阶段卡住了。 · Use when debugging connection timeouts
"Can we dump the JSON-RPC traffic to stderr?"
我们能把 JSON-RPC 流量输出到标准错误流吗？ · Use when requesting verbose logging for debugging
"It seems the server failed to negotiate capabilities."
服务器似乎未能成功协商能力/特性。 · Use when diagnosing handshake failures
"We need to dynamically expose these internal APIs as MCP tools."
我们需要将这些内部 API 动态暴露为 MCP 工具。 · Use during architectural discussions about tool integration
"The orchestrator is choking on the malformed tool response."
编排器因为格式错误的工具响应而崩溃/卡顿。 · Use when the LLM client fails to parse the server's output
The Model Context Protocol (MCP) standardizes how AI models access external data and tools. By decoupling the orchestrator from the underlying data sources, MCP enables a highly modular architecture. When an MCP client connects to a server, it initiates a JSON-RPC handshake over a chosen transport, such as standard input/output (stdio) or Server-Sent Events (SSE). During this phase, both parties negotiate capabilities.
If the server successfully initializes, it can expose specific resources, prompts, and tools to the client. However, developers must carefully manage the transport layer; if a subprocess writes non-protocol logs or debugging information to stdout instead of stderr, it will corrupt the JSON-RPC stream. This frequently causes the orchestrator to abruptly drop the connection, citing a malformed payload or initialization timeout.
Comprehension Check
1. What happens during the initial connection phase between an MCP client and server?
2. Which transport mechanisms are explicitly mentioned in the passage?
3. What will likely cause the orchestrator to abruptly drop the connection?
You just fixed #TKT-8924. The Claude Code CLI was dropping its connection to your custom MCP server because a third-party library was logging warnings to `stdout`, which polluted the JSON-RPC stream. Write a brief ticket update.
- 1.State the root cause clearly
- 2.Explain your fix (redirecting logs to stderr)
- 3.Use the term "transport" or "JSON-RPC stream"
- 4.Keep it under 80 words
3 Words from Previous Lessons
短暂的 / 临时的
Used for short-lived containers, tokens, or states.
内省 / 自省
The ability of a system to examine its own schemas or state.
差异 / 不一致
Used when two environments or expected outputs do not match.
2 Expressions from Previous Lessons
"It looks like the MCP server is silently swallowing the error."
"Let's tail the logs to see where the handshake drops."
In an MCP architecture, what are the security trade-offs between using a local `stdio` transport versus a remote `SSE/HTTP` transport when exposing internal backend APIs to an AI Agent? Describe at least one distinct risk for each approach.
Answer in English. Use technical vocabulary from this lesson. No word limit.