| name | mcp-ops-troubleshooting |
| description | Diagnose an existing MCP server, preset, connection, discovery, authentication, schema, transport, or tool-execution failure. Use for MCP operations and recovery; use mcp-server-builder to create/register a new MCP server and integration-setup for broader service setup. |
MCP operations troubleshooting
Locate the failing layer before changing configuration.
- Inspect the durable
connection_ops attempt and canonical connection record before lower-level MCP state.
- Separate discovery, plan, OAuth/token exchange, MCP initialization, session negotiation, tool discovery, exposure policy, and tool execution.
- For Streamable HTTP, inspect status, content type,
Mcp-Session-Id, protocol version, and complete SSE event framing. Never parse a network chunk as a complete SSE event.
- Use
mcp_server_manage for targeted status/connect/list-tools diagnostics without replacing the durable setup flow.
- Inspect one failing schema and run the smallest exposed read-only tool.
- Change one layer at a time and repeat the identical probe.
- Finish with
connection_ops(action:"verify", ...), non-empty approved tool exposure, and a real safe read.
Never print secrets or “fix” auth by broadening scopes blindly. An empty tool list is a state to explain, not proof that the runtime is broken.
Read detailed-guide.md for transport-specific checks, logs, preset fields, schema issues, timeout recovery, and test matrices.
