MCP troubleshooting · reviewed October 8, 2026

MCP server not connecting? Find the first failing layer.

Identify the transport and protocol era before changing configuration. Follow one testable diagnostic step at a time.

Get the free checklist Full debugging kit · $9

1. Identify the transport and failure boundary

stdio: the client launches a local process and communicates over stdin/stdout. Check executable path, arguments, environment, working directory, process exit code, and stderr. Ordinary logs on stdout can corrupt protocol messages.

Streamable HTTP: the client connects to an HTTP endpoint. Check DNS/TLS, exact MCP endpoint path, authorization, redirects, proxy behavior, and HTTP status. A successful browser GET does not prove MCP POST works.

Define the exact symptom: launch failure, connection failure, discovery failure, or tool execution failure. They require different experiments.

2. MCP 2025 and MCP 2026 use different lifecycles

Legacy revisions through 2025-11-25 use initialize followed by notifications/initialized. An HTTP session ID may matter depending on the server and transport.

MCP 2026-07-28 removes the protocol-level initialize handshake and session ID. Modern requests carry version and client capabilities in per-request metadata; server/discover can advertise supported versions. Missing initialize is normal in the modern era.

Inspect the selected protocol version rather than guessing from the SDK package version. Check the official 2026 release notes and version compatibility specification before migrating an existing client/server pair.

3. Diagnose one layer at a time

  1. Runtime: reproduce the exact configured command for stdio.
  2. Transport: verify stdin/stdout or HTTP reachability.
  3. Protocol: identify legacy initialize versus modern stateless requests.
  4. Discovery: test tools/list separately from tool execution.
  5. Execution: call one harmless read-only tool with synthetic input.
  6. Compatibility: compare client policy, auth, timeouts, and selected protocol era.

4. Interpret common symptoms

  • Process exits: inspect runtime, path, environment, and stderr.
  • HTTP 401/403: inspect authorization and policy.
  • HTTP 404: inspect endpoint path and routing.
  • HTTP 406/415: inspect content negotiation.
  • Legacy initialize fails: inspect protocol compatibility.
  • Modern request rejected: inspect protocol version and per-request metadata.
  • tools/list works but tools/call fails: inspect handler, input schema, upstream, and timeout.

5. Record evidence

Capture versions, transport, selected protocol era, first failing operation, status, sanitized error, and one control experiment. Change one variable at a time.

Reusable resources

Download the free checklist for a compact version of this diagnostic flow.