Skills.

“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

Get the next article

Sent when I publish, together with the free skill used here. No spam, one-click unsubscribe.

Payment processed by Stripe — no card data touches this server. Instant delivery once confirmed. Prices in BRL (Brazilian real) — you are charged in BRL. Terms, delivery and refund.