Your MCP server works in the terminal and fails in the client — the four causes

“Works here” and “works in the client” are two different programs. These four
failures account for nearly every MCP server that passes the local test and dies on the first
real call — and none of them is the server's code.

1. A short connect timeout kills a long call

If the server boots a heavy backend on first use (instrumented browser, container, model), the
connect phase can take a minute. A 5-second connect_timeout drops the session
mid-call, and the message you get does not say that.

connect_timeout: 60 # not 5 — the backend boots lazily
Size the timeout by the minimum observed boot time, not by a warm call's latency.

2. A 401 that is not a dead server

The app answers its health check, the MCP returns 401. That is not downtime: it is the API
key header missing from the MCP entry. The error shows up in the tool, not in the config — so
you debug the wrong layer.

headers:
X-API-Key: ${WEB_RESEARCH_API_KEY} # resolved from env, never inline
Test in two layers: (a) does the app answer? (b) is the header in the MCP entry? Different
failures, same face.

3. A config read at import is inert

You fix the config file, restart only the server, and it still fails. If the config was read at
import time, it is frozen in memory — the change only applies on the next boot of whoever
imported it. Read it at the point of use, or restart the importer.

4. Dead session mid-call: outcome UNKNOWN

transport session expired … outcome UNKNOWN means the server restarted under you.
The call did not complete — and “UNKNOWN” is not success. Confirm with the health check's
uptime (a few seconds = it restarted), retry once, and if it repeats, report it.

Retrying a call that already returned a definitive error burns the budget and hides the real
blocker.

Before you call it done

Verify a fresh config with the cheapest call available (a ping) before real work, and re-verify
after any restart. An MCP server that answers a ping and fails its first tool is a server you
never tested end to end.

See the Ship Your MCP Server skill
See all skills

Want this wired into your project? Guided setup from
R$ 1.500, with the first cycle run together.

← all skills