mcp-debug

Name: mcp-debug
Author: chacosoldier

29stars6forks

How to install mcp-debug?

chacosoldier/compabob/mcp-debug

$npx -y skills add chacosoldier/compabob --skill mcp-debug

Installs into the current project.

Summary

MCP server health check, tool tracing, and audit. Use when MCP tools fail silently, to check server status, or for periodic system audits. Trigger: /mcp-debug [status|trace|audit]

Files · 1

View on GitHub

SKILL.md

1	# MCP Debugger
2
3	A diagnostic tool for MCP (Model Context Protocol) server health and tool execution. Helps identify why MCP tools fail, which servers are down, and which servers are unused or redundant.
4
5	Reads MCP config from the two standard locations:
6	- `~/.claude.json` — user-scope servers.
7	- `<project>/.mcp.json` — project-scope servers.
8
9	## Mode detection
10
11	Check the arguments:
12	- No args or `status` — health check all configured MCP servers.
13	- `trace <tool-name>` — trace a specific tool's configuration and likely failure modes.
14	- `audit` — full audit with recommendations (unused servers, error patterns, consolidation candidates).
15
16	## Mode 1: Status (default)
17
18	### Steps
19
20	1. List configured servers via the Claude Code CLI:
21	```bash
22	claude mcp list
23	```
24	If the CLI is unavailable, parse `~/.claude.json` (top-level `mcpServers`) and `./.mcp.json` directly.
25
26	2. For each server, run the lightweight connectivity check appropriate to its transport:
27	- stdio — confirm the command exists on `$PATH` (`which <bin>`) and the wrapper script is executable.
28	- http / sse — `curl -s -o /dev/null -w "%{http_code}"` the URL.
29	- Authenticated remote — a `401` or `403` means reachable, not down. Flag as `auth` rather than `error`.
30
31	3. Present a status table:
32
33	\| Server \| Transport \| Status \| Note \|
34	\|---\|---\|---\|---\|
35	\| foo \| stdio \| ok \| \|
36	\| bar \| http \| auth \| 401 — token may need refresh \|
37	\| baz \| stdio \| error \| binary not on PATH \|
38
39	4. For `warning`/`error` rows, propose the next debugging step (install the binary, refresh the token, check the env var).
40
41	### Output
42
43	```
44	## MCP Server Status
45
46	[table]
47
48	### Issues found
49	- <server>: <description + suggested fix>
50
51	### Summary
52	[X] ok \| [Y] warnings \| [Z] errors out of [N] servers
53	```
54
55	## Mode 2: Trace
56
57	### Steps
58
59	1. Parse the tool name from args (e.g. `/mcp-debug trace some-tool`).
60
61	2. Find which server provides this tool. The MCP tool naming convention is `mcp__<server-slug>__<tool-name>`; the server slug maps back to a key in `~/.claude.json` or `.mcp.json`.
62
63	3. Show the server's configuration:
64	- Transport (stdio / http / sse).
65	- Command or URL.
66	- Args.
67	- Env vars (always redact secrets — show `***` instead of values for any key matching `(?i)(token\|key\|secret\|password)`).
68
69	4. Classify the likely failure mode:
70	- Auth expired — OAuth token needs refresh.
71	- Schema mismatch — tool expects different parameters than what was sent.
72	- Timeout — server takes too long to respond.
73	- Server down — process crashed or port unreachable.
74	- Config error — missing env var, wrong path, or stale wrapper script.
75
76	### Output
77
78	```
79	## Tool trace: <tool-name>
80
81	Server: <server>
82	Transport: stdio \| http \| sse
83	Command / URL: <value>
84	Status: <from health check>
85
86	### Configuration
87	[relevant config — secrets redacted]
88
89	### Likely cause
90	<classification + suggested fix>
91	```
92
93	## Mode 3: Audit
94
95	### Steps
96
97	1. Run the status check (Mode 1) for the full server list.
98
99	2. If tool-usage telemetry exists (some projects log to `data/performance/session-log.jsonl` or similar), summarise the last 7 days:
100	- Tools called per server.
101	- Error rate per server.
102	- Most-used and least-used servers.
103
104	3. Identify:
105	- Unused servers — configured but never called. Candidates for removal (each one adds startup overhead).
106	- High-error servers — called often but failing frequently.
107	- Duplicate capabilities — multiple servers providing similar tools.
108	- Missing servers — tools referenced in agents/skills but no server configured.
109
110	### Output
111
112	```
113	## MCP audit report
114	Date: YYYY-MM-DD
115	Servers: <N> configured
116
117	### Health summary
118	[status table]
119
120	### Usage (last 7 days)
121	\| Server \| Calls \| Errors \| Error rate \|
122	\|---\|---\|---\|---\|
123	[from session logs, or "no usage data available"]
124
125	### Recommendations
126	1. Remove: <servers not used in 7+ days, with rationale>
127	2. Fix: <servers with high error rates>
128	3. Consolidate: <servers with overlapping capabilities>
129	4. Add: <missing servers referenced by agents>
130	```
131
132	## Constraints
133
134	- Never expose secrets. Redact API keys, tokens, passwords in every output.
135	- Read-only. This skill does not start, stop, or modify any servers or config.
136	- Do not delete servers without explicit user approval.
137	- `401`/`403`/`405` on URL servers = reachable, not down. Mark as `auth` so the operator knows to refresh credentials rather than restart the server.
138
139	## Quality checklist
140
141	- [ ] All MCP config locations checked (`~/.claude.json` + `.mcp.json`).
142	- [ ] Secrets redacted in every output line.
143	- [ ] False-positive warnings (e.g. spaces in command paths handled by the shell) are flagged as such, not as errors.
144	- [ ] Recommendations include a one-line rationale, not ju

People who liked this also viewed

6 picks

Type

mcp-debug

29stars6forks

View on GitHub

How to install mcp-debug?

chacosoldier/compabob/mcp-debug

$npx -y skills add chacosoldier/compabob --skill mcp-debug

Installs into the current project.

Summary

MCP server health check, tool tracing, and audit. Use when MCP tools fail silently, to check server status, or for periodic system audits. Trigger: /mcp-debug [status|trace|audit]

Files · 1

View on GitHub

SKILL.md

1	# MCP Debugger
2
3	A diagnostic tool for MCP (Model Context Protocol) server health and tool execution. Helps identify why MCP tools fail, which servers are down, and which servers are unused or redundant.
4
5	Reads MCP config from the two standard locations:
6	- `~/.claude.json` — user-scope servers.
7	- `<project>/.mcp.json` — project-scope servers.
8
9	## Mode detection
10
11	Check the arguments:
12	- No args or `status` — health check all configured MCP servers.
13	- `trace <tool-name>` — trace a specific tool's configuration and likely failure modes.
14	- `audit` — full audit with recommendations (unused servers, error patterns, consolidation candidates).
15
16	## Mode 1: Status (default)
17
18	### Steps
19
20	1. List configured servers via the Claude Code CLI:
21	```bash
22	claude mcp list
23	```
24	If the CLI is unavailable, parse `~/.claude.json` (top-level `mcpServers`) and `./.mcp.json` directly.
25
26	2. For each server, run the lightweight connectivity check appropriate to its transport:
27	- stdio — confirm the command exists on `$PATH` (`which <bin>`) and the wrapper script is executable.
28	- http / sse — `curl -s -o /dev/null -w "%{http_code}"` the URL.
29	- Authenticated remote — a `401` or `403` means reachable, not down. Flag as `auth` rather than `error`.
30
31	3. Present a status table:
32
33	\| Server \| Transport \| Status \| Note \|
34	\|---\|---\|---\|---\|
35	\| foo \| stdio \| ok \| \|
36	\| bar \| http \| auth \| 401 — token may need refresh \|
37	\| baz \| stdio \| error \| binary not on PATH \|
38
39	4. For `warning`/`error` rows, propose the next debugging step (install the binary, refresh the token, check the env var).
40
41	### Output
42
43	```
44	## MCP Server Status
45
46	[table]
47
48	### Issues found
49	- <server>: <description + suggested fix>
50
51	### Summary
52	[X] ok \| [Y] warnings \| [Z] errors out of [N] servers
53	```
54
55	## Mode 2: Trace
56
57	### Steps
58
59	1. Parse the tool name from args (e.g. `/mcp-debug trace some-tool`).
60
61	2. Find which server provides this tool. The MCP tool naming convention is `mcp__<server-slug>__<tool-name>`; the server slug maps back to a key in `~/.claude.json` or `.mcp.json`.
62
63	3. Show the server's configuration:
64	- Transport (stdio / http / sse).
65	- Command or URL.
66	- Args.
67	- Env vars (always redact secrets — show `***` instead of values for any key matching `(?i)(token\|key\|secret\|password)`).
68
69	4. Classify the likely failure mode:
70	- Auth expired — OAuth token needs refresh.
71	- Schema mismatch — tool expects different parameters than what was sent.
72	- Timeout — server takes too long to respond.
73	- Server down — process crashed or port unreachable.
74	- Config error — missing env var, wrong path, or stale wrapper script.
75
76	### Output
77
78	```
79	## Tool trace: <tool-name>
80
81	Server: <server>
82	Transport: stdio \| http \| sse
83	Command / URL: <value>
84	Status: <from health check>
85
86	### Configuration
87	[relevant config — secrets redacted]
88
89	### Likely cause
90	<classification + suggested fix>
91	```
92
93	## Mode 3: Audit
94
95	### Steps
96
97	1. Run the status check (Mode 1) for the full server list.
98
99	2. If tool-usage telemetry exists (some projects log to `data/performance/session-log.jsonl` or similar), summarise the last 7 days:
100	- Tools called per server.
101	- Error rate per server.
102	- Most-used and least-used servers.
103
104	3. Identify:
105	- Unused servers — configured but never called. Candidates for removal (each one adds startup overhead).
106	- High-error servers — called often but failing frequently.
107	- Duplicate capabilities — multiple servers providing similar tools.
108	- Missing servers — tools referenced in agents/skills but no server configured.
109
110	### Output
111
112	```
113	## MCP audit report
114	Date: YYYY-MM-DD
115	Servers: <N> configured
116
117	### Health summary
118	[status table]
119
120	### Usage (last 7 days)
121	\| Server \| Calls \| Errors \| Error rate \|
122	\|---\|---\|---\|---\|
123	[from session logs, or "no usage data available"]
124
125	### Recommendations
126	1. Remove: <servers not used in 7+ days, with rationale>
127	2. Fix: <servers with high error rates>
128	3. Consolidate: <servers with overlapping capabilities>
129	4. Add: <missing servers referenced by agents>
130	```
131
132	## Constraints
133
134	- Never expose secrets. Redact API keys, tokens, passwords in every output.
135	- Read-only. This skill does not start, stop, or modify any servers or config.
136	- Do not delete servers without explicit user approval.
137	- `401`/`403`/`405` on URL servers = reachable, not down. Mark as `auth` so the operator knows to refresh credentials rather than restart the server.
138
139	## Quality checklist
140
141	- [ ] All MCP config locations checked (`~/.claude.json` + `.mcp.json`).
142	- [ ] Secrets redacted in every output line.
143	- [ ] False-positive warnings (e.g. spaces in command paths handled by the shell) are flagged as such, not as errors.
144	- [ ] Recommendations include a one-line rationale, not ju

People who liked this also viewed

6 picks

Type