MCP server debugging playbook: auth, transport, schema

Map initial symptoms into auth, transport, or schema categories.

Classification first prevents random fix attempts.

Check token scope, expiry, and source precedence.

Ensure local and CI read the same credential source.

Verify endpoint reachability, proxy rules, and TLS from the failing environment.

Use minimal probes to establish a stable baseline.

Compare payload fields and version markers against expected contract.

Use known-good and failing fixtures to isolate parser drift quickly.

Validate both minimal repro and real workflow after patching.

Update runbook with root cause and preventive checks.