mcpaudit

mcpaudit

Point it at any MCP server. Get a score, and the receipts.

The MCP Registry is filling up with servers nobody has ever audited. A server can list tools with no descriptions (so models never call them correctly), schemas that contradict themselves (required fields that don't exist), or — the dangerous one — cheerfully return success when you call a tool that doesn't exist. None of that shows up until a user's agent does something weird in production.

mcpaudit launches the server the way a real client does, runs the full handshake, inspects every tool, deliberately makes a bad call, and prints one scored report with named, evidence-backed issues. No LLM anywhere in the audit: every check is deterministic and repeatable.

What it checks

check	what it proves
handshake	The server completes initialize — and how long it took
protocol version	The negotiated version is present and one this build knows
server info	serverInfo.name and serverInfo.version are present
tool names	Present, unique, and inside the MCP character/length guidance
descriptions	Every tool described, in more than a token gesture, not just its own name repeated
input schemas	Present, an object schema, valid properties, required fields that actually exist
parameter docs	Tools whose parameters are all undescribed get flagged — models guess semantics from descriptions
error handling	A call to a nonexistent tool returns a proper error, fast, without killing the server
prompts / resources	A server with no tools is not failed for it: when it advertises prompts/resources, mcpaudit lists them and audits it as what it is

Scoring: start at 100, each error costs 8, each warning costs 3. Verdicts: PASS (clean), WARN (works, but the issues will cost it users or correctness), FAIL (error-severity issues), UNREACHABLE (the handshake never completed — reported with the launch error, never a guessed score).

mcpaudit audits stdio servers. Remote (HTTP) servers — config entries with a url, or a URL passed as the command — are reported as UNREACHABLE with that explanation, never silently skipped and never spawned.

New in 0.1.1, from the first real-production validation battery (25+ external servers, three runs each, findings hand-checked against raw ground truth): server arguments starting with -- pass through verbatim (see Usage), prompt/resource-only servers pass, the default per-step timeout is 60s so npx/uvx cold starts are not mistaken for dead servers, and --json always emits one parseable document.

Usage

CLI

# Audit a server by its launch command
npx @reneturcios/mcpaudit audit npx -y @reneturcios/shipcheck mcp
npx @reneturcios/mcpaudit audit node dist/cli.js mcp

# Audit every server in an MCP client config (or one named entry)
npx @reneturcios/mcpaudit audit --config ~/.claude/claude_desktop_config.json
npx @reneturcios/mcpaudit audit --config ./mcp.json --server greenlight

# Server arguments that start with -- pass through untouched
npx @reneturcios/mcpaudit audit uvx mcp-server-git --repository /path/to/repo

# Use a literal -- to force everything after it into the server command
# (even flags that share a name with mcpaudit's own, like --timeout)
npx @reneturcios/mcpaudit audit node server.js -- --timeout 5000

# Quoted command line, machine-readable output, custom timeout
npx @reneturcios/mcpaudit audit --cmdline "npx -y @scope/pkg mcp" --json --timeout 30000

# Offline: validate a tools/list dump without launching anything
npx @reneturcios/mcpaudit tools tools.json

Example output:

mcpaudit npx -y @reneturcios/shipcheck mcp: PASS (score 100/100, grade A)
  server: shipcheck 0.1.0 · protocol 2025-11-25 · 3 tool(s) · initialize 1813ms · tools/list 16ms
  error handling: bad tool call returned a proper error
  No issues found.
PASS: handshake, schemas, and error handling all check out.

(That is a real run, from the first MCP Server Index seed, 2026-10-22. Initialize time is measured from spawn and includes npx cold-start overhead, and the report says so. A slow initialize is only scored when the server itself is slow once running: if tools/list answers within 5s, a 30s+ initialize is reported as unscored launch path evidence, because that time went to the launcher or to first-run downloads.)

Exit codes: 0 for PASS/WARN, 1 for FAIL/UNREACHABLE, 2 for usage errors — CI-ready.

MCP server

Add to your MCP client config:

{
  "mcpServers": {
    "mcpaudit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/mcpaudit", "mcp"]
    }
  }
}

Tools:

• audit_server: launch and audit one server from a command + args (+ optional env, timeout).
• audit_config: audit every server in a config file, or one named entry.
• audit_tools: offline validation of a tools/list array.

Docker

docker run -i ghcr.io/cloudcorprecords/mcpaudit mcp
docker run --rm ghcr.io/cloudcorprecords/mcpaudit audit node server.js mcp

The MCP Server Index

mcpaudit is the engine behind a growing public dataset, the MCP Server Index: scored audits of real, published MCP servers, run with the published binary and refreshed as servers ship. The seed — the author's own tool family, audited first because you audit yourself before you audit anyone else — lives in the 100-packages workspace and grows with every wave.

The toolkit

mcpaudit is Wave 1, package 4 of a planned family of small, single-purpose developer tools by the same author, all built the same way: one bin that serves a CLI and an MCP server, deterministic checks with evidence, no invented answers.

• greenlight: pre-flight checks for open-source contributions: is this issue actually landable?
• shipcheck: release verification — git tag, GitHub release, npm, MCP Registry, and GHCR must all agree, or NO-GO.
• cidiff: base-vs-head CI differ for PRs.
• reprocheck: red-first repro verifier.
• prwatch: attention report for your open PRs.
• claimcheck: stale-claim states and parked fixes on forks.
• gatefile: extract hidden contribution gates into machine-readable contribution-gates.json.
• pkgverdict: pre-install verdicts for npm packages: GO, RISKY, FAKE, or MISSING.

Development

npm install
npm run build
npm test   # validator/scoring unit tests + live probes against fixture servers

License

MIT