Debugging MCP in Production: A Practical Checklist

Official tooling: MCP Inspector and Debugging. Use this checklist in order.

1. Is the deployment alive?

• Process/status running; no crash loop
• Correct artifact (git SHA / image tag)
• Recent logs without fatal exceptions

2. Can the client reach the URL?

Streamable HTTP (transports):

• Single MCP endpoint supports POST (and GET as specified)
• Client Accept headers / content types as required
• Origin validation not blocking legitimate clients (invalid Origin → 403)
• TLS / corporate proxy issues

Legacy remotes: follow backwards compatibility probe rules for HTTP+SSE.

Local stdio: verify command/args and that stdout is clean JSON-RPC only.

3. Auth

• Token/OAuth present and not expired
• Scheme matches server expectation
• 401/403 in logs
• No token passthrough bugs (security best practices)
• Sessions: if MCP-Session-Id required, client sends it; session ≠ authentication

See authorization and auth patterns.

4. Lifecycle / discovery

1. initialize succeeds (lifecycle)
2. notifications/initialized path completed as required
3. tools/list returns expected names (tools)
4. Schemas valid JSON Schema objects

5. Single tool failure

Distinguish protocol errors vs tool execution errors (tools error handling).

6. Intermittent issues

• Multi-instance session stickiness / resumability (transports sessions)
• Rate limits (servers MUST rate limit — tools security)
• Cold start / scale-to-zero
• Agent retry storms (cost control)

Data you need

Fix patterns

Worked scenario: The empty tools list at 4pm

A staging deploy shows Running. Cursor connects. No tools appear.

You open logs and see the process crash-looping on a missing env var—then restarting just long enough for the TCP health check. The host’s initialize sometimes races a healthy second of uptime, sometimes not.

You fix it by: (1) checking deploy logs before the host UI, (2) confirming initialize + tools/list with the MCP Inspector, (3) separating protocol errors from isError tool results, and (4) adding an alert on auth failures and tool error rate—not only CPU.

Next incident is different: one tool fails with opaque text. You improve the tool’s execution error message so the model stops retrying the same bad arguments.

Checklist for this topic

• Confirm process is stable (no crash loop) before debugging the host
• Reproduce with Inspector: initialize → tools/list → tools/call
• Classify protocol error vs isError tool execution error
• Verify transport match (stdio config vs Streamable HTTP URL)
• Check auth (token, Origin, session header if used)
• Capture last good artifact id for rollback

Topic-specific failure modes

Related guides

Observability · Transports · Testing

In practice: a 15-minute triage order

When Slack says “MCP is down,” resist opening the host first.

1. Deployment status + last 50 log lines — crash loops beat clever theory.
2. Inspector against the same URL the host uses — if Inspector cannot tools/list, the host is innocent.
3. Auth probe — unauthenticated request should fail; authenticated should initialize.
4. One known-good tool — proves execution path beyond discovery.
5. Diff last deploy — schema or auth changes explain most sudden breaks.

Only after those five do you dig into multi-instance session stickiness or rare race conditions. Most “mysterious” issues die at step 1–3.

Capture pack for incidents

When paging, attach:

• Deployment name + artifact id
• Timestamp window
• tools/list snapshot (names)
• One failing tools/call payload (redacted)
• Auth mode
• Host type (Cursor/Claude/VS Code/custom)

Missing capture packs turn every incident into archaeology.

Takeaways

For Debugging MCP in Production: A Practical Checklist, remember three things:

1. Be specific to this problem — the worked scenario “The empty tools list at 4pm” is the failure mode you should design against, not a generic outage narrative.
2. Separate transport/auth failures from tool logic failures before you rewrite business code.
3. Capture tool name, error class, latency, and client identity on every failed invocation.

If you only remember one habit: start every incident with initialize + tools/list + one known-good tools/call against the failing URL.

Sources

• MCP Inspector
• Debugging
• Transports — 2025-11-25
• Tools — 2025-11-25
• Lifecycle — 2025-11-25
• Security Best Practices
• Connect to remote MCP servers

Next steps

Observability · Testing