INTERNAL MSP AUTOMATION PLATFORM
Claude Code CLI failing to discover local MCP server tools
I am integrating a custom MCP server into our MSP platform to expose customer ticketing tools to the Claude Code CLI. However, during initialization, the CLI hangs and fails to fetch the tools. The handshake completes, but the tool discovery phase times out.
我正在将一个自定义的 MCP (Model Context Protocol) 服务器集成到我们的 MSP 平台中，以便将客户工单工具暴露给 Claude Code CLI。然而，在初始化期间，CLI 卡住并无法获取暴露的工具。握手已完成，但工具发现阶段超时。
The degree to which a system's APIs or tools can be found and understood automatically by a client.
"We need to improve the discoverability of the MCP tools so the agent can invoke them dynamically."
An automated process of negotiation between two entities to set up the rules of communication.
"The stdio transport is dropping packets before the initial handshake completes."
To examine the internal state, logs, or structure of a system to diagnose an issue.
"Let's inspect the JSON-RPC payload being sent from the Claude Code CLI."
To make internal functions, ports, or tools available to external services or clients.
"Make sure you expose the create_ticket function correctly in the MCP server configuration."
The mechanism (like stdio or SSE) used to transmit messages between the MCP client and server.
"Switching the transport layer from stdio to Server-Sent Events (SSE) might resolve the connection drop."
The actual data transmitted in an API request or message, excluding headers and metadata.
"The server is rejecting the request because the tool invocation payload doesn't match the advertised schema."
"The CLI is hanging during the tool discovery phase."
CLI 在工具发现阶段卡住了。 · Use when a process is stuck without throwing an immediate error
"Let's tail the logs and see what the MCP server is actually receiving."
我们跟踪一下日志，看看 MCP 服务器到底收到了什么。 · Use when debugging real-time communication issues
"It looks like a schema mismatch between the advertised tool and the LLM's invocation."
看起来暴露的工具和 LLM 的调用之间存在 Schema 不匹配。 · Use to point out incompatible data structures
"Can you verify if the transport layer is over stdio or SSE?"
你能确认传输层是通过 stdio 还是 SSE 吗？ · Use to check the foundational connection setup
"We need to gracefully handle the timeout instead of crashing the whole agent loop."
我们需要优雅地处理超时，而不是让整个 Agent 循环崩溃。 · Use during PR reviews regarding error handling
The Model Context Protocol (MCP) standardizes how AI models interact with local and remote data sources. An MCP architecture consists of a client, such as the Claude Code CLI, and an MCP server. The server exposes specific capabilities, typically categorized as Resources, Prompts, or Tools.
During the initialization phase, the client establishes a connection via a transport layer—commonly using `stdio` for local processes or Server-Sent Events (SSE) for remote servers. A critical step is the handshake, where both parties agree on the protocol version. Once connected, the server advertises its tools using JSON schemas, allowing the client to discover and invoke them. If tool discoverability fails, it is often due to a malformed JSON-RPC payload or a schema validation error on the server side causing the connection to hang.
Comprehension Check
1. What is the primary purpose of the MCP standard described in the text?
2. Which transport layer is commonly used for local MCP processes?
3. According to the passage, what is a common cause if tool discoverability fails?
Write a short technical update to your team via Slack regarding the CLI discovery issue.
- 1.State the root cause clearly (e.g., malformed JSON schema).
- 2.Mention the transport layer being used (stdio or SSE).
- 3.Propose a quick workaround or next step.
- 4.Keep it under 80 words.
3 Words from Previous Lessons
编排
Coordinating multiple agents or services to work together.
隔离 / 定位
To separate a specific issue or component for debugging.
协议
A standard set of rules for data formatting and processing.
2 Expressions from Previous Lessons
"The MCP server is failing to advertise its tools."
"Let's isolate the issue by bypassing the proxy."
When implementing an MCP server that exposes tools to an LLM, why is it critical to validate the JSON-RPC payload from the client *before* executing the tool, rather than relying solely on the LLM's understanding of the advertised schema? Provide two specific risks of skipping this validation.
Answer in English. Use technical vocabulary from this lesson. No word limit.