Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-triage scan all my MCP configs and fix any broken ones"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Triage broken MCP setups across agent clients. A NeufAgents tool. One command scans the MCP configuration of every agent client on your machine, finds what is broken or fragile, explains it in plain English, and — where it is safe — repairs it. It runs as a CLI, and as a stdio MCP server (mcp-triage serve) so an agent client can run triage itself.
Why triage: a triage assesses severity fast and routes the case — a free check-and-fix pass for the mechanical problems, and a precise hint (plus a human path) for setups that need surgery.
Scans (8 clients): Claude Desktop · Claude Code (incl. project-scoped servers from ~/.claude.json) · Codex · Cursor · VS Code · Windsurf · OpenClaw · dsh
Checks (v0.1): JSON syntax (including the classic trailing comma), Codex-style TOML tables (basic), command resolvable on PATH, missing ${VAR} / process.env.VAR references, relative-path arguments, plain http:// remote URLs, transport/entry consistency (stdio needs a command, HTTP transports need a url, serverName required for dsh entries), cross-client drift for same-named servers
Fixes (opt-in --fix): mechanical repairs, only for files that fail to parse — strips JSON comments and trailing commas, re-verifies the result, keeps a .mcp-triage.bak backup. Everything else is escalated with a hint, never guessed at.
JSON5-aware: OpenClaw's openclaw.json is JSON5 (comments + trailing commas legal) and is parsed as such — no false syntax errors
CLI-first: runs even when your client cannot start — that is exactly when you need it
MCP server mode (mcp-triage serve): the same pipeline as MCP tools — triage_scan (read-only) and triage_fix (dry-run by default) — so any MCP client can run triage itself
Zero runtime dependencies (including in server mode)
Related MCP server: sentinel-scan
npx mcp-triage # scan standard locations (all clients) + project configs in cwd
npx mcp-triage --json # machine-readable output
npx mcp-triage --file ./my-config.json
npx mcp-triage --fix # repair files that fail to parse (comments / trailing commas)
npx mcp-triage --fix --dry-run # show what --fix would do; write nothing
npx mcp-triage serve # run as an MCP server (stdio) — see "MCP server mode" belowExit codes: 0 = no error findings, 1 = at least one error finding (post-fix when --fix is used).
--fix semantics (v0.1)Only files that fail to parse are fix candidates; healthy files are never rewritten.
Repairs are mechanical deletions only (comments, trailing commas). A repaired copy must parse as JSON or nothing is written.
Before the first write the original is saved as <file>.mcp-triage.bak (an existing backup is kept, never overwritten — so the pristine version survives repeated runs).
A demo machine with three clients — one broken JSON, one unrunnable command, one healthy config:
$ npx mcp-triage scan
MCP Triage v0.1.0 — scanned 3 config file(s)
✗ Claude Desktop — ~/AppData/Roaming/Claude/claude_desktop_config.json — 0 server(s)
✓ Codex — ~/.codex/config.toml — 2 server(s) (toml-minimal)
✓ Cursor — ~/.cursor/mcp.json — 1 server(s)
Findings (4):
[ERROR] config.syntax — Claude Desktop: Trailing comma breaks JSON parsing
line 5: "args": ["-y", "@modelcontextprotocol/server-memory"],
→ Remove the comma before the closing bracket/brace, then restart the client.
[ERROR] server.command-unresolvable — Codex · "notes-mcp": command "my-notes-mcp" not found on PATH
→ This is the #1 cause of "server silently missing" bugs. Common causes: nvm-managed node (the client does not load your shell profile), missing pnpm/uv, or a typo. Use an absolute path or install the runtime the client can see.
[WARN ] server.relative-path-arg — Codex · "notes-mcp": Relative path argument "./notes" may resolve from the wrong directory
→ Clients spawn servers from their own working directory. Use an absolute path to make this stable.
[INFO ] config.cross-client-drift — Codex · "filesystem": Server "filesystem" is configured differently across 2 clients
codex → ~/.codex/config.toml
cursor → ~/.cursor/mcp.json
→ Drift is not always wrong — but when one client works and another does not, this is where to look.
Summary: 2 error(s), 1 warning(s), 1 info — 3 server(s) across 3 file(s).--fix takes care of the mechanical class — and nothing else:
$ npx mcp-triage --fix
Fix results:
[FIXED] Claude Desktop — ~/AppData/Roaming/Claude/claude_desktop_config.json: removed 1 trailing comma
→ backup: ~/AppData/Roaming/Claude/claude_desktop_config.json.mcp-triage.bak
Summary: 1 error(s), 1 warning(s), 1 info — 4 server(s) across 3 file(s).Sample output from a demo machine; home paths shortened for readability. --fix --dry-run prints the same report with [DRY] instead of [FIXED], and writes nothing.
All 8 client paths are verified against official docs and/or a real machine (verification log: docs/verification-log.md in the repo). OpenClaw paths additionally honor OPENCLAW_CONFIG_PATH; VS Code includes the remote/WSL user config (~/.vscode-server/data/User/mcp.json).
JSON clients: full parsing (OpenClaw: JSON5-light — comments and trailing commas; exotic JSON5 beyond that still fails). TOML (Codex): basic — [mcp_servers.*] tables only. YAML (dsh cordis profiles): light — per-entry extraction of @deepseek-ai/dsh-mcp-client patch entries (serverName, transport, command, args, env, cwd; !!js expressions kept as text for reference checks).
Claude Code project-scoped mcpServers inside ~/.claude.json (projects.*.mcpServers) are scanned too — identical definitions across projects are merged into one entry whose context lists the projects, and findings carry the project path.
--file on a file we cannot attribute to a client: if it only parses as JSON5, you get an info saying so (not an error) — strict-JSON clients would reject such a file.
mcp-triage serve runs the same pipeline as a stdio MCP server, so an agent client can run triage itself. Register it like any other MCP server:
{
"mcpServers": {
"triage": { "command": "npx", "args": ["-y", "mcp-triage", "serve"] }
}
}Tools:
triage_scan — read-only scan; same discovery and checks as the CLI, returns the full report.
triage_fix — mechanical repairs. Dry-run by default: nothing is written unless the call passes dry_run: false. Same guarantees as the CLI: parse-gated writes, .mcp-triage.bak backup kept.
Both tools run on the machine where the server runs; stdout carries protocol messages only (logs go to stderr).
--fix is not enough--fix covers the mechanical class — for free. For everything else (a client that still refuses to start after a clean scan, a setup you want hardened before it breaks, a migration across machines), NeufAgents offers a paid fix service: send your triage report to hi@neufagents.com and you get a written scope before any work starts. Fully async, no calls.
npm install
npm test # node:test, 66 specs — dev/test scripts need Node 22.18+ (native type stripping)
npm run build # tsc → dist/
node src/cli.ts scan
node src/cli.ts scan --fix --dry-run
node src/cli.ts serve # MCP server in dev (same Node 22.18+ requirement)The dev and test scripts import .ts files directly, so they need Node 22.18+. The published package
itself supports Node 20+ (engines) and its scan / --fix / serve flows are smoke-tested on Node 20.19.
CI runs the full spec suite on Node 22 and a build + --version smoke on Node 20 on every push and pull request.
The package is ESM with zero runtime dependencies; src/index.ts is the library entry
(import { discoverFiles, parseConfigFile, runChecks, applyFixes } from 'mcp-triage'),
src/cli.ts is the mcp-triage binary, and src/serve.ts is the stdio MCP server (also
re-exported from the library entry). prepack builds dist/; prepublishOnly runs the specs.
MIT © NeufAgents (neufagents.com)
Repair MCP config files that fail to parse — mechanical repairs only (strip JSON comments and trailing commas). Dry-run by default: unless dry_run is explicitly false, nothing is written. A .mcp-triage.bak backup is kept before any write, and nothing is written unless the repaired copy parses cleanly.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory whose project-level configs are included (default: the server process working directory). | |
| file | No | Fix this single config file instead of the standard locations. | |
| dry_run | No | When true (the default), report what would be fixed and write nothing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations declaring readOnlyHint=false, the description adds crucial behavioral detail: dry-run by default, backup creation before any write, and a safety check that nothing is written unless the repaired copy parses cleanly. This goes well beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, zero filler. The core action is front-loaded, followed by essential safety behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with no output schema, this description is nearly complete: it explains what gets repaired, the default mode, backup, and validation. A minor gap is the lack of precedence rules when both cwd and file are provided, but that is a detail rather than a blocking omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so cwd, file, and dry_run are all described in the input schema. The description reinforces dry_run's default behavior but does not add new parameter meaning beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Repair MCP config files that fail to parse', and narrows the scope with 'mechanical repairs only (strip JSON comments and trailing commas)'. This clearly distinguishes it from the sibling triage_scan, which is a scan tool by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use when config files fail to parse and need mechanical fixes. However, it does not explicitly name alternatives or state when not to use it (e.g., for non-mechanical issues), so it falls short of the highest bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan the MCP configuration files of the agent clients on this machine (Claude Desktop, Claude Code, Codex, Cursor, VS Code, Windsurf, OpenClaw, dsh) and report findings: broken JSON/TOML, commands not on PATH, missing env vars, relative-path arguments, plain-http remotes, transport mismatches, and cross-client drift for same-named servers. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Directory whose project-level configs are included (default: the server process working directory). | |
| file | No | Scan this single config file instead of the standard locations. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the description doesn't need to repeat the read-only nature (though it does, harmlessly). It adds valuable behavioral context by listing the specific issue categories scanned (broken JSON/TOML, PATH issues, env vars, relative paths, plain-http remotes, transport mismatches, cross-client drift), which goes beyond annotations. It does not describe the output format or error handling, but that is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that front-loads the main action and then lists the checks. It is not padded with fluff, though it is somewhat long due to the enumeration. It earns its length by specifying what the tool scans and what it reports, but could be slightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description says it 'reports findings' but does not specify the output structure (e.g., a summary list, detailed report). It also does not mention any limitations (e.g., which clients are supported). However, the list of checks gives a good sense of the tool's coverage. With the annotations and parameter schema already present, this is adequately complete for a read-only diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% – both parameters (cwd and file) have descriptions that fully explain their purpose. The tool description does not add any additional meaning or examples for these parameters, so it relies on the schema. Baseline 3 is appropriate when the schema carries the full semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Scan') with a clear resource ('MCP configuration files of the agent clients') and enumerates the exact checks performed. It distinguishes itself from the sibling triage_fix by explicitly labeling itself 'Read-only', so an agent can tell them apart without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for diagnostics (scan and report) while the sibling triage_fix handles fixes, but it never explicitly mentions triage_fix or gives conditions like 'use this when you need to inspect configs without modifying'. The 'Read-only' tag provides strong context, but explicit alternative routing is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0triage_fixtriage_scanScored across 2 tools
The two tools are sharply delineated: triage_scan is read-only and reports problems, while triage_fix performs repairs. There is no overlap in purpose or output.
Both tools follow the same 'triage_' prefix plus a clear verb ('scan', 'fix'). The naming pattern is uniform and predictive.
With only two tools, the set is slightly below the typical 3-15 range, but scan/fix form a natural pair for a focused triage utility. No redundant tools exist.
triage_scan detects a wide range of configuration issues (PATH, env vars, transport mismatches, etc.), but triage_fix only repairs parse failures. This creates a significant gap: many detected issues have no corresponding fix action.
Scans remote MCP servers for protocol, security, and TLS issues; exposes scan tools via MCP.
Scan any MCP server for tool-poisoning, security, auth & license. Trust score before install.
Scan any website or MCP server for agent readiness: 0-100 score, a fix per failing check. Free.
Workflow diagnostics, capability routing, and x402 settlement for MCP-compatible agents.