Failure Modes & Debugging

Triage First

Does the server's capability even show up (tools, resources, prompts)?
   │
   ├── No  → discovery / capability negotiation problem
   │
   └── Yes, but calling it fails
        │
        ├── Rejected before it runs (schema error) → schema/arguments problem
        │
        ├── Never reaches the server at all → transport/auth problem
        │
        └── Runs, but the result looks wrong or manipulative → untrusted-server problem

Symptom to Cause

Discovery and Capability Negotiation

Mechanism: A client only attempts operations for capabilities it declared support for in its own _meta.clientCapabilities, and only for capabilities the server actually advertised in its server/discover response. If either side is silent about a capability, the other treats it as unsupported — there's no implicit "try it and see."

// Client that never declared elicitation support
"clientCapabilities": { "tools": {} }

// A server offering an elicitation-dependent tool will not be usable —
// the client has no declared way to handle the elicitation/create round trip

Fix: When a server's tools/resources/prompts don't show up, check both sides of the negotiation — what the server's server/discover response actually advertises, and what the client declared it can handle. A mismatch on either side produces the same silent "nothing appeared" symptom.

Schema and Argument Mismatches

Mechanism: tools/call arguments are checked against the tool's declared inputSchema. A rejection here is a contract problem, not an intelligence problem — if the schema is ambiguous (a loosely-typed field, an unclear enum, a missing required list), the model has genuinely insufficient information to construct valid arguments reliably.

// Ambiguous: is "date" a specific format? Required or optional?
{ "date": { "type": "string" } }

// Fixed: format and requirement are explicit
{ "date": { "type": "string", "format": "date", "description": "YYYY-MM-DD" } },
"required": ["date"]

Fix: Tighten the schema before assuming the calling model needs to be "smarter." A precise inputSchema with explicit formats, enums, and a complete required list resolves the large majority of argument-validation failures.

Authorization Loops and Token Confusion

Mechanism: Per Authorization & Security, an access token is requested for one specific server via the resource parameter (RFC 8707), and the server validates the token was issued specifically for it. Two distinct problems produce similar-looking symptoms:

Fix: For a genuinely stuck flow, check the resource parameter is present and correct on both the authorization and token requests. For "rejected by a different server," there's nothing to fix — request a token for that specific server instead.

Transport-Specific Assumptions That Don't Survive Redeployment

Mechanism: A server built and tested only over stdio can accumulate assumptions that are true locally but false once it's redeployed remotely over Streamable HTTP: that it only ever serves one client at a time, that credentials can come from the local environment implicitly, that there's no need to handle concurrent requests.

Fix: Treat "will this run remotely eventually" as a design question from the start, even for a server currently running over stdio — retrofitting multi-client and auth assumptions after the fact is significantly more work than building for them from the outset.

Concept Checks

Key Concepts Recap

Next

With the failure modes catalogued, the next page walks through one complete, worked design that gets these decisions right from the start: Designing an MCP-Based System.