An MCP tool timeout means a caller stopped waiting. To fix it, identify the last completed protocol stage, correlate the request with server execution, and find the deadline that actually expired. Raising a tool's internal timeout helps only when that timeout is the limiting layer.
This guide is a diagnostic procedure, checked against documentation on November 16, 2026. Client configuration names and protocol revisions differ. Record the client, server, SDK versions, transport and negotiated protocol before copying a setting from another installation.
First locate the failed stage
| Last confirmed event | What to inspect next | Evidence that narrows the cause |
|---|---|---|
| Server launch requested, no process ready | Executable, working directory, runtime, environment and startup stderr | Exit status or startup exception; a GUI can have a different PATH from your terminal |
| Process or HTTP endpoint reachable, discovery incomplete | Protocol compatibility, authentication and the actual discovery exchange | Request sent but no matching response, or an explicit protocol/authentication error |
| Tools listed, call never reaches handler | Host approval, routing, argument validation and queue admission | Client dispatch timestamp compared with handler-entry timestamp |
| Handler starts, downstream operation stalls | Database/API timeout, lock contention, worker saturation | Correlated downstream start/end and server exception |
| Server finishes, client still times out | Response serialization, transport, proxy and caller deadline | Result-emitted timestamp, proxy trace and response-received timestamp |
Treat these as hypotheses, not diagnoses based on one log line. A healthy endpoint proves reachability; a tool list proves discovery; neither proves that the requested business operation works.
There is an important version fork. Legacy MCP uses initialize and then notifications/initialized before normal operations. The current Inspector also documents a modern 2026-07-28 era using server/discover. Its default is legacy, with explicit auto and modern choices. Match the era to the integration under test before interpreting a missing handshake response. Legacy lifecycle, Inspector protocol eras.
Run the smallest safe test outside the agent loop
Use the official MCP Inspector with the same executable, working directory, relevant environment, endpoint, credentials and protocol era as the failing host. Start with discovery, then an explicitly read-only tool and a tiny known input. Inspector supports browser and CLI inspection. Follow its version's launch instructions; executing a server package executes its code, so use a trusted, reviewed package. Inspector guide.
For example, the documented CLI form for a local Node server is:
npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list
Replace the path with your actual server. For reproducibility, record the installed Inspector version and pin that reviewed version for repeat tests. This command is an official usage example, not a claim that your server has been tested.
If Inspector also fails, inspect server and transport evidence first. If it succeeds, compare environments and request traces with the original host. Success in a different client narrows the investigation; it does not prove a particular host bug.
For stdio, inspect the wrapper as well as the server. Startup banners and debug prints on stdout can corrupt the protocol stream. Send ordinary logs to stderr and preserve stdout for protocol messages. MCP stdio transport.
Build a deadline ledger
For one failing request, collect a redacted record like this:
trace: diagnostic-17
protocol / transport / client-version / server-version: ...
request sent: +0.000 s
handler entered: +0.120 s
downstream started: +0.135 s
caller stopped: +10.000 s
downstream ended: +12.400 s
result emitted: +12.410 s
business outcome: read-only / committed / failed / unknown
These are illustrative timestamps, not a production measurement. Use monotonic elapsed times within a process; account for clock skew when correlating machines. Log request IDs and a separate business-operation ID, never bearer tokens or private tool arguments.
List each timer's owner, unit, start event and reset condition: startup, queue wait, SDK request, downstream request, proxy idle, host overall and user cancellation. Two settings both called timeout can measure different intervals. A proxy idle timer and a total request deadline are especially easy to confuse.
Choose budgets from the intended operation and measured latency. Leave room for the server to return a controlled downstream failure before its caller gives up, while respecting the host's overall limit. This is an engineering budgeting rule, not a universal MCP setting or fixed number of seconds.
Progress, cancellation and retries are different mechanisms
Progress reports can improve visibility. In the legacy lifecycle specification, resetting a timeout on progress is optional, and a maximum total timeout is still recommended. Sending progress therefore cannot guarantee that a host, SDK or proxy extends its deadline. Verify actual receive times and the client's reset policy. Timeout rules.
Cancellation is version-sensitive too. Legacy HTTP disconnection alone is not cancellation; the modern Inspector documents closing a request's SSE response stream as the modern HTTP cancellation signal. Over stdio it still uses cancellation notifications. Match behavior to the negotiated era. Legacy transport, current Inspector cancellation behavior.
Even a cancellation request is not a rollback receipt. Legacy cancellation explicitly allows races with completed work and operations that cannot be cancelled. For a write, check the durable business result before retrying. If the outcome is unknown, reconcile by operation ID; use the service's documented idempotency mechanism where available. Never invent an idempotency field and assume the server honors it. Cancellation specification.
For intrinsically long work, evaluate a supported task mechanism or an application-level submit/status design. Verify both endpoints' capabilities, persistence, cancellation and result retrieval. A job identifier is useful only if it can recover the actual operation after disconnection.
Prove the fix with controlled failure cases
Run these in a local fixture or staging environment, with synthetic read-only work. Change one variable per trial and retain the request trace.
| Injection | Expected diagnostic observation | Fix acceptance |
|---|---|---|
| Delay server startup | Discovery fails before any handler entry | Normal startup succeeds; slow startup reports a bounded, attributable failure |
| Delay a tool beyond the caller deadline | Handler entry exists; caller gives up first | Intended-duration call completes, excessive work still terminates within the chosen policy |
| Send progress while delaying completion | Progress arrives, but the total outcome depends on client policy | Observed reset behavior matches configuration; total limit remains bounded |
| Break the response path after a synthetic operation completes | Client failure coexists with server completion | Recovery checks the outcome before any repeat operation |
These are a test plan, not reported test results. Record the installed versions and observed outcomes when you execute it. Test the original host again after Inspector passes, including a fresh connection and one normal real read-only result.
The closure criterion is specific: identify the expiring layer, reproduce its failure, show the original request now completes correctly, and preserve bounded failure and safe recovery. A longer spinner is insufficient evidence.
For the broader interface decision, see MCP versus CLI: execution and trust boundaries.