Diagnose MCP connection and tool failures with a fixed playbook. Expand rows with product-specific codes at GA — keep this symptom → check order.
Connection
| Symptom | Check |
|---|---|
| Server does not appear | Host config JSON validity; restart host |
| Tools list empty | Token present; correct server URL; scopes enabled |
| 401 / unauthorized | Bearer spelling; token rotated; wrong environment |
| 403 / forbidden | Scope missing for that server or tool |
| TLS / network errors | Corporate proxy; allowlist MCP hosts |
Tool calls
| Symptom | Check |
|---|---|
| Validation errors | Args vs schema; required page |
| Timeouts | Rate limits; large list pages; retry with backoff |
| Unexpected empty data | Workspace ACL; wrong org token; staging vs prod |
| Write rejected | Missing write scope; confirmation policy |
Multi-server confusion
- Confirm the agent targeted Docs vs Platform vs AI — identical tool names should not collide if configs are separate entries.
- If using the legacy single URL, expect Platform-only tools.
Collect for support
- Agent host + version
- MCP server URL (no token)
- Tool name and timestamp
- Whether REST works with the same token
Chat with support if blocked after these checks.