CLAUDE CODE CLI / MCP INTEGRATION
MCP Server fails to initialize tools during handshake
I am trying to integrate a custom MCP server with the Claude Code CLI to enable local PostgreSQL querying. However, the CLI hangs during the initialization phase, and the tool definitions are not being registered in the context window. We need to debug the transport layer to see if the JSON-RPC payload is malformed.
在尝试将自定义的 MCP 服务器与 Claude Code CLI 集成以实现本地 PostgreSQL 查询时，CLI 在初始化阶段挂起，工具定义未能注册到大模型的上下文窗口中。我们需要排查传输层通信，确认 JSON-RPC 格式是否正确。
The act of triggering or executing a function, tool, or API endpoint.
"The LLM's tool invocation failed because the mandatory parameters were missing from the JSON payload."
The underlying mechanism used to pass messages between the client and server (e.g., stdio, SSE).
"Claude Code CLI uses stdio as the default transport for local MCP servers, preventing the need for exposed network ports."
A secondary process spawned and managed by a parent program to execute a specific task.
"The MCP client launches the server as a local subprocess, so any crash in the server won't tear down the whole agent."
The sequence of states an object, connection, or process goes through from creation to termination.
"We need to handle the complete MCP server lifecycle, including sending graceful shutdown signals to prevent resource leaks."
The required setup phase where systems connect, authenticate, or exchange capabilities before operation.
"The handshake stalled during the initialization sequence because the server returned an invalid JSON schema."
"The CLI is hanging during the tool discovery phase."
CLI 在工具发现阶段挂起了。 · Use when describing a stuck process during initialization
"Let's check if the client and server agree on the protocol version."
检查一下客户端和服务器的协议版本是否一致。 · Use when debugging handshake failures
"I suspect the transport layer is dropping packets over stdio."
我怀疑传输层在通过 stdio 通信时丢包了。 · Use when investigating intermittent I/O issues
"Let's tail the logs and see what the MCP server is actually receiving."
我们追踪一下日志，看看 MCP 服务器到底接收到了什么。 · Use during live debugging sessions
"The tool execution failed because of a schema mismatch."
由于模式不匹配，工具执行失败了。 · Use when LLM payload doesn't fit the expected parameters
The Model Context Protocol (MCP) establishes a standardized architecture for connecting AI models to external data sources and tools. When integrating an MCP server with a client like the Claude Code CLI, the transport mechanism is critical. Typically, local servers operate via stdio, acting as a subprocess where JSON-RPC messages are exchanged over standard input and output streams.
During initialization, the client and server perform a handshake to negotiate protocol versions and advertise capabilities. If the server fails to expose its tool schema correctly during this phase, the client cannot inject those capabilities into the LLM's context window. This often results in the CLI hanging or returning an invocation error. To troubleshoot, engineers must isolate the transport layer, verify the JSON-RPC payload, and ensure no background processes are interfering with the stdio streams and lifecycle events.
Comprehension Check
1. What transport mechanism is typically used for local MCP servers in this context?
2. Why might the CLI hang during the initialization phase?
3. According to the passage, what must engineers verify to troubleshoot an invocation error?
Write a brief update in Jira ticket #TKT-8492 explaining your progress.
- 1.State that you successfully reproduced the CLI hang issue.
- 2.Mention that the root cause appears to be a schema mismatch during initialization.
- 3.Propose debugging the transport layer logs to inspect the JSON-RPC payloads.
- 4.Keep it concise (under 80 words).
3 Words from Previous Lessons
可发现性
How easily a client can find advertised tools.
暴露 / 公开
Making an API or tool schema available to clients.
模式 / 架构
The structural definition of expected parameters.
2 Expressions from Previous Lessons
"The MCP server is failing to advertise its tools."
"It looks like a schema mismatch between the advertised tool and the LLM's invocation."
When implementing a Multi-Agent System using MCP, why is it risky to rely entirely on a single stdio-based local MCP server for all agents? Discuss potential bottlenecks and suggest an alternative transport or orchestration architecture.
Answer in English. Use technical vocabulary from this lesson. No word limit.