MCP is connected but a tool fails: how do you locate the failing stage?
An MCP connected status only establishes that a connection stage completed; it does not establish that the business API behind a tool works. Check initialization, tool discovery and execution separately, starting with one minimal request without side effects.
Start troubleshooting here
An MCP connected status only establishes that a connection stage completed; it does not establish that the business API behind a tool works. Check initialization, tool discovery and execution separately, starting with one minimal request without side effects. Record where the error occurs, then distinguish protocol compatibility, invalid parameters and downstream failures instead of repeatedly reconnecting.
Record client versions and the actual transport
This applies when a client displays the server name but cannot list tools, or lists tools that always fail. Record the client and server versions and the transport in use. A green connection indicator is not evidence of business success, and discovering a tool does not establish that the current account can access the intended resource.
Check initialization, discovery and execution separately
Confirm that initialization completed and check the negotiated protocol version and capabilities. Then inspect the tool list for the expected name and input schema before making a minimal read-only call. With standard input/output transport, ordinary logs must not contaminate protocol output. For remote connections, check network reachability and business API authentication separately.
Fix one minimal read-only call at the failing stage
Reduce the failure to one tool and explicit parameters, retaining the request identifier and complete error type. If discovery fails, fix startup and capability negotiation. If arguments are invalid, correct them against the current schema. If the protocol returns a business error, investigate the downstream service rather than labeling every exception an offline MCP server.
Verify the tool with a real response from the intended resource
The verification record should separately establish initialization, discovery of the expected tool and a successful minimal real query. Confirm that the response comes from the intended resource. If reconnection only helps intermittently, repeat the originally failing call. An empty response must be checked against the query conditions; absence of an error alone does not establish completion.
Clients may define connection states differently, so use actual protocol records. This article did not connect a new MCP service or read account credentials. Check token configuration sources and authorization scopes without printing real values. Do not grant an unfamiliar tool extra write privileges or access to all files merely to test it.
Checked sources
These sources support the concepts and methods described here. Examples and test scope are labeled separately; check the version of the tools you use.