What it does
Give the agent a disciplined MCP triage sequence.
This skill separates launch, initialization, tool-call, transport, and path-boundary failures. It asks for the evidence needed to select a branch, then orders reversible checks before destructive changes.
Works with
Compatible instruction surfaces
- Codex custom skills or project instructions
- Claude Code project instructions
- Other coding agents that accept reusable instructions
When to use it
Use it for a real MCP failure
Use this when an MCP server will not launch, initialize, stay connected, or return a tool result. Include the exact client, OS, server, transport, and error. For syntax and common field checks, first validate your MCP configuration.
Installation
Add it to the narrowest useful scope
- Copy the skill content into your agent's supported project-instruction or skill file.
- Keep it scoped to repositories where MCP troubleshooting is needed.
- Tell the agent which client, operating system, and failing server it should inspect.
Skill content / source
Copy the instruction
You are diagnosing an MCP failure. Stay scoped to the named client, server, operating system, and exact error.
1. Record the client version, server package/version, transport, OS, shell, and launch context.
2. Preserve the exact error and the 30 log lines before it. Redact secrets without changing paths or error text.
3. Validate configuration syntax and field types before changing dependencies.
4. For a local stdio server, resolve the command from the same environment that launches the client. Check command, args, working directory, PATH, and required non-secret environment variable names.
5. Separate launch failure, initialize/handshake failure, tool-call failure, and transport disconnection. Do not treat them as the same problem.
6. On Windows or WSL, identify the path namespace used by the client and server. Do not mix drive-letter, UNC, and /mnt paths without evidence that the boundary supports it.
7. Run one reversible check at a time and state the expected observation.
8. Do not output or request secret values. Do not recommend disabling security controls as a default fix.
9. Conclude with: observed evidence, likely branch, next safest test, verification step, and remaining uncertainty.Example
Start from an exact failure
Client: Claude Desktop on Windows. Server: local stdio package launched with npx. Exact error: spawn npx ENOENT. Diagnose command resolution from the desktop process environment before changing the package.
Limitations
What it cannot establish
- It does not replace client-specific MCP documentation or prove a root cause from one error line.
- It cannot inspect logs, processes, or configuration that you have not made available to the agent.
- Remote HTTP and OAuth-based MCP servers may need a client-specific diagnostic path.
Security notes
Keep diagnostics safe
- Redact tokens, cookies, passwords, private keys, and authorization headers before sharing logs or configuration.
- Do not weaken sandbox or permission boundaries merely to make an error disappear.
- Prefer reversible checks before reinstalling software or deleting state.
Related troubleshooting