CLAUDE CODE CLI / ORCHESTRATOR
MCP Server fails to expose local resources via stdio transport
We are integrating a custom MCP server into the Claude Code CLI using the stdio transport. However, the client is timing out during the initialization phase and failing to retrieve the exposed file resources. We need to debug the JSON-RPC payload and fix the handshake process.
我们正在将自定义的 MCP server 通过 stdio 传输层集成到 Claude Code CLI 中。但是，客户端在初始化阶段发生超时，并且无法获取暴露的文件资源。我们需要调试 JSON-RPC 的数据载荷并修复握手流程。
Standard input/output streams used as a local transport mechanism for MCP communication.
"For local testing, we run the MCP server over stdio instead of relying on a remote HTTP connection."
An independent process launched and managed by a parent host program.
"The Claude CLI spawns the custom server as a subprocess to keep the main agent thread unblocked."
The initial negotiation phase where the client and server agree on supported capabilities.
"If the server doesn't respond with valid JSON-RPC during the handshake, the connection drops immediately."
The actual core data transmitted in an API or RPC message, excluding headers.
"Make sure your print statements aren't corrupting the JSON-RPC payload returning to the client."
To make internal tools, interfaces, or resources available to external clients.
"The server needs to explicitly expose the local database read functions as MCP tools."
The degree to which tools or endpoints can be easily found and listed by an automated client.
"Providing clear JSON schemas for your tools improves their discoverability by the LLM orchestrator."
"The client is hanging during the init phase."
客户端在初始化阶段卡住了。 · Use when a process is stuck without crashing.
"Let's dump the JSON-RPC traffic to stderr."
我们把 JSON-RPC 流量转储到标准错误输出看看。 · Use when debugging transport issues without breaking stdio.
"It looks like the server failed to negotiate capabilities."
看起来服务器未能成功协商功能支持。 · Use when the handshake protocol fails.
"Is the server exposing the correct schema for this tool?"
服务器为这个工具暴露的 schema 正确吗？ · Use during tool integration troubleshooting.
"We need to isolate whether it's a transport issue or a logic bug."
我们需要排查这究竟是传输层问题还是逻辑层 bug。 · Use when proposing a debugging strategy.
The Model Context Protocol (MCP) standardizes how AI models interact with local and remote environments. When connecting an MCP client to a local server, the most common transport layer is stdio. The client launches the server as a subprocess and communicates directly via standard input and output streams.
During the initialization phase, the client and server exchange a handshake to negotiate capabilities. If the server incorrectly writes any debugging statements or non-JSON-RPC logs to stdout, the payload becomes corrupted, and the client will typically hang or timeout. To prevent this, all internal logs must be explicitly routed to stderr.
Once the handshake completes successfully, the server can expose tools, resources, and prompts, ensuring high discoverability for the orchestrating AI agent.
Comprehension Check
1. What transport layer is primarily discussed for local MCP servers?
2. What happens if the server writes debugging logs to `stdout`?
3. Where should debugging logs be routed when using this transport?
Write a brief Slack update to your team explaining why the new MCP integration is failing.
- 1.State the current blocking issue (client timeout during init).
- 2.Explain the root cause (stdout is polluted with debug logs).
- 3.Propose the next step (route logs to stderr).
- 4.Keep it under 80 words.
3 Words from Previous Lessons
间歇性的
Happening occasionally, not constantly.
替代方案 / 变通方法
A temporary fix to bypass a problem.
隔离 / 定位
To separate a problem to find the root cause.
2 Expressions from Previous Lessons
"The server is choking on the initialization request."
"Let's tail the logs to see where the handshake drops."
When designing a multi-agent system using MCP, what are the architectural trade-offs between using a local `stdio` transport versus a remote `SSE` (Server-Sent Events) transport for your MCP servers?
Answer in English. Use technical vocabulary from this lesson. No word limit.