Debug MCP failures by finding the first step that breaks: process launch, transport connection, protocol negotiation, capability discovery, tool listing, or tool execution. For a local stdio server, start with the executable and launch environment. For an HTTP server, confirm the endpoint, transport, and authorization. If the client connects but shows no tools, inspect the server’s advertised capabilities and returned tool list before investigating an individual tool.
Start by locating the first failure
Record the client and server SDK names and versions, configured transport, launch command or endpoint, and exact first error. Then classify the failure by stage rather than treating every connection problem as a protocol mismatch.
- Launch: Did the client start the local server process?
- Transport: Did stdio or HTTP communication begin?
- Negotiation: Did the peers establish a compatible protocol session?
- Discovery: Did the server advertise capabilities and return tools?
- Execution: Is a listed tool failing when called?
The TypeScript SDK’s protocol guide distinguishes timeouts, authorization responses, server errors, and unusable successful responses; those signals point to different layers. See the TypeScript SDK protocol-version guide.
Debug local stdio launch failures
With stdio, the client transport launches and owns the server child process, then exchanges JSON-RPC messages over its stdin and stdout. If the client is configured to spawn the server, do not also start a separate copy while troubleshooting; check the process the client actually launched.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- COMPLETE TESTING KIT: This professional bundle pairs the flagship VDV II Pro cable verifier with a 12-piece numbered remote set, providing a complete solution to map, test, and troubleshoot copper cabling.
- ADVANCED FAULT FINDING: The VDV II Pro uses TDR technology to accurately measure cable length and identify distance to faults, ensuring you locate opens, shorts, and miswires with precision.
- INCREASED PRODUCTIVITY: The 12 active remote units (#1–#12) allow you to test and identify multiple cable runs from a single location, eliminating the need to move back and forth between outlets.
- MULTIMEDIA VERSATILITY: Equipped with RJ-11, RJ-45, and Coax F-Type ports, the tester supports voice, data, and video media, plus provides in-built network detection for Ethernet rate and duplex information.
- CLOUD-CONNECTED EFFICIENCY: Sync test data effortlessly via the TREND AnyWARE Cloud App to generate professional PDF reports, streamlining your documentation and workflow on the job site.
When the error says spawn npx ENOENT
This means the launching process cannot resolve npx as an executable on its PATH. Verify that the executable exists and that the MCP client’s process environment can find it. Check the working directory, executable name, and arguments in the same launch context used by the client—not only in a separate interactive terminal. The TypeScript SDK’s first-client example demonstrates the client-owned child-process setup.
Keep stdout reserved for protocol messages
stdio protocol messages use stdout, so ordinary diagnostic output there can interfere with communication. Send diagnostics through the host’s supported logging channel or the child’s stderr. The SDK example forwards child stderr as a banner. Also preserve the transport’s process lifecycle: it closes the child when the client closes, and cleanup should run in a finally block when later failures could otherwise leave the process running.
Check the HTTP endpoint and transport
For a remote server, confirm the exact endpoint path and which HTTP transport the server implements. Streamable HTTP and the older HTTP+SSE transport are distinct; a client configured for one should not be assumed to work with a server that only supports the other.
The TypeScript SDK’s connection guide uses StreamableHTTPClientTransport for remote servers. If that connection attempt fails and you suspect the server is legacy SSE-only, retry with a fresh client using SSEClientTransport. That is a transport-compatibility check, not a fix for bad credentials, a server outage, or a broken endpoint.
Interpret negotiation errors and HTTP responses
Protocol negotiation varies by SDK version and protocol revision. The TypeScript SDK documents a newer discovery flow using server/discover and an older initialize handshake, with automatic negotiation able to fall back when appropriate. The Python SDK likewise documents discovery followed by an initialize fallback when discovery fails or the server does not support the latest version. Check the versions and negotiation mode on both sides before concluding they disagree; consult the TypeScript and Python SDK protocol guides.
Rank #3
In the TypeScript SDK’s documented behavior, these responses are not interchangeable:
- HTTP 401 or 403: authorization or permission failure, not evidence by itself that the server uses an older protocol.
- HTTP 5xx: server-side failure.
- Timeout: an outage or reachability problem; the SDK does not silently treat an HTTP probe timeout as proof of an older server.
- Unusable 2xx response: not valid evidence of an older protocol; a successful status with an unusable body is still a bad response.
- Browser CORS exception: investigate browser or gateway policy as a separate compatibility issue.
These interpretations describe the SDK guide, not a guarantee that every client handles responses identically. Verify the behavior of the actual client version. If a reverse proxy or gateway sits between peers, check that it preserves the HTTP method, MCP headers, expected response content type, and streaming behavior. The SDK documentation does not prescribe one universal proxy configuration.
Rank #4
When the client connects but no tools appear
Run the client’s tool-list operation and inspect the returned names, descriptions, and input schemas. If the list is empty, investigate server-side registration and capability declarations before debugging tool-call arguments.
Check capability registration
In the TypeScript SDK, the high-level McpServer installs handlers for declared primitive capabilities. With the low-level Server, the developer registers handlers directly. A high-level server can declare tools yet return an empty list if none were registered. If the list operation itself fails, check whether the server registered or advertised the relevant capability and whether the client and server SDK versions are compatible. The TypeScript SDK v1-to-v2 migration guide explains the distinction between the high- and low-level server APIs.
Best Value
- COMPLETE TEST & TRACE ESSENTIALS – This professional bundle pairs the VDV II Basic Cable Verifier with a high-sensitivity Amplifier Probe, providing a complete solution to verify wiring integrity and trace copper cable routes in voice, data, and video applications.
- RAPID WIREMAP TROUBLESHOOTING – The VDV II Basic identifies complex wiring faults quickly and efficiently. It checks the integrity of copper cables found in telephone wiring, data networks, and security cabling, ensuring every connection is accurate.
- HIGH-PRECISION CABLE TRACING – Pinpoint signals with the included Amplifier Probe, featuring a powerful 20dB gain and visual signal strength LED. The recessed volume dial and 3.5mm audio jack allow for clear identification even in noisy environments or crowded cabinets.
- ALL-IN-ONE MULTIMEDIA SUPPORT – Save time with integrated RJ-45 (data), RJ-11/12 (voice), and Coax F-type (video) connectors. This versatile kit eliminates the need for separate adapters or multiple testers when working on diverse low-voltage systems.
- DURABLE & FIELD-READY DESIGN – Engineered for long hours on the job, the Amplifier Probe offers superior 50-hour battery life and an integrated LED flashlight for dark workspaces. Generate professional PDF reports effortlessly using the TREND AnyWARE Cloud App.
Separate a missing tool from a failing tool
Compare the requested tool name exactly with the names in the returned list. A name the server never registered is a protocol-level failure in the TypeScript client example. By contrast, a handler exception or arguments that fail the input schema are returned there as a tool result with isError: true. For a listed tool that fails, validate the arguments against its advertised schema before investigating the handler.
Build a useful diagnostic record
Capture enough evidence to identify the failing layer without exposing credentials:
- Client and server SDK names and versions, plus the protocol revision or negotiation mode if available.
- Configured transport and, for stdio, the exact executable and arguments; for HTTP, the endpoint path.
- The exact error, HTTP status, and relevant client and server logs.
- Whether connection completed, the capability response, and the raw tool list.
- For stdio, whether the launching process can see the executable in its own environment; for HTTP, whether the endpoint uses Streamable HTTP or legacy SSE and whether authorization or a gateway interrupts negotiation.
Redact tokens, credentials, and other secrets from commands, endpoints, and logs before sharing them.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
