CLAUDE CODE CLI / MCP INTEGRATION
Claude Code CLI fails to discover local MCP tools via stdio transport
Our new Daily English Lab agent is failing to initialize its tools via the Model Context Protocol (MCP). The Claude Code CLI spawns the local Java server and connects using the stdio transport layer, but it hangs indefinitely during the tool discovery phase. We suspect this is due to a malformed JSON-RPC payload returning from the server.
我们的新日常Lab Agent在使用模型上下文协议（MCP）初始化工具时失败。Claude Code CLI成功启动了本地Java服务并使用stdio传输层建立连接，但在工具发现阶段无限期挂起。我们怀疑这是因为服务端返回了格式错误的JSON-RPC payload。
For an unlimited or unspecified period of time, often causing a system hang.
"The MCP client is blocking indefinitely while waiting for the server's initialization response."
Badly shaped or structured, violating the expected protocol or JSON schema.
"The JSON-RPC payload was rejected by the orchestrator because it was malformed."
The act of calling or executing a function, method, or external tool.
"We need to log the exact tool invocation to see which arguments the LLM actually passed."
To initiate the execution of a new process or thread from a parent application.
"The Claude Code CLI will spawn our Java server as a subprocess and communicate over stdio."
To assign a specific task, request, or responsibility to another component.
"The orchestrator delegates complex PSA queries to a specialized MCP server."
To catch or block a request or stream of data before it reaches its destination.
"We can use a custom inspector to intercept the stdio traffic and debug the payload."
"The process is hanging on startup."
进程在启动时卡死了 · Use when a server fails to fully boot but doesn't explicitly crash.
"Let's tail the logs."
我们跟踪一下日志 · Use when actively monitoring the real-time output of a process.
"It's failing silently."
它在后台静默失败了/没报错就失败了 · Use when a bug occurs without throwing any exceptions or explicit error messages.
"Can we mock the tool response?"
我们可以mock一下工具返回数据吗？ · Use when testing an agent's orchestration logic without hitting real APIs.
"There's a schema mismatch."
Schema/数据结构不匹配 · Use when the payload structure doesn't align with what the receiving service expects.
The Model Context Protocol (MCP) provides a standardized way for Large Language Models to interact with external tools and data sources. When connecting an MCP server to an orchestrator like LangGraph or Claude Code, the client typically spawns the server as a subprocess. In this configuration, communication natively occurs over the standard input/output (stdio) transport layer.
During the initialization phase, the client and server exchange a handshake to verify protocol compatibility and discoverability. If the JSON-RPC payload is malformed or if there is a schema mismatch in the advertised tools, the client may hang indefinitely or fail silently. To debug these issues, engineers should intercept the communication stream to ensure that every tool invocation strictly adheres to the requested JSON schema before the task is delegated to the execution environment.
Comprehension Check
1. What happens if the MCP client and server encounter a schema mismatch during initialization?
2. According to the passage, how does the client typically launch the MCP server?
3. What is the recommended way to troubleshoot a failing MCP handshake?
You are investigating why the Claude Code CLI hangs when discovering your local Java MCP server. Write a short update in the Jira ticket (TKT-8842).
- 1.State that the server is being spawned correctly as a subprocess.
- 2.Mention that the client hangs indefinitely during the initialization/discovery phase.
- 3.Propose intercepting the stdio traffic to check for a malformed JSON-RPC payload.
- 4.Keep it concise (under 80 words).
3 Words from Previous Lessons
子进程
A process spawned by another process, typical for stdio MCP connections.
可发现性
The capability for a client to detect and list available tools on the server.
有效载荷 / 数据主体
The actual data packet transmitted, like the JSON-RPC request.
2 Expressions from Previous Lessons
"The CLI is hanging during the tool discovery phase."
"Let's check if the client and server agree on the protocol version."
When using the stdio transport for an MCP server, what are the primary challenges regarding observability and error handling compared to a standard HTTP/REST architecture? How would you mitigate them?
Answer in English. Use technical vocabulary from this lesson. No word limit.