mcpgrade

Lighthouse for MCP servers. Your server can be 100% spec-compliant and still fail agents — vague descriptions, token-bloated schemas, confusable tool names. mcpgrade scores what compliance checkers can't: whether an LLM can actually use your tools.

npx mcpgrade https://your-server.example.com/mcp   # streamable HTTP
npx mcpgrade --stdio "node ./my-server.js"          # local stdio server
npx mcpgrade --snapshot tools.json                  # saved tools/list output

Zero config. No API key. Report in seconds.

What it checks

Category	Weight	Examples
Descriptions	30%	missing/too-short descriptions, undocumented params, placeholder text, duplicate descriptions
Schema design	30%	missing types, no required array, additionalProperties: true, prose-instead-of-enum, deep nesting
Naming	15%	confusable names (get_user vs get_users), generic verbs (process), mixed conventions
Token cost	15%	catalog total budget, per-tool budget — agents pay your schema on every request
Consistency	10%	catalog-wide uniformity; with --probe, live checks that error messages help the model self-correct

Every finding comes with a concrete fix. Scores are density-normalized: 3 broken tools out of 3 is an F; 3 out of 30 is a dent.

Example

mcpgrade — agent usability report
target: examples/bad-server.json · 4 tools

  F   37/100

  Descriptions   ░░░░░░░░░░░░░░░░░░░░   0
  Naming         ███████████░░░░░░░░░  55
  Schema design  ███░░░░░░░░░░░░░░░░░  13
  Token cost     ████████████████████ 100
  Consistency    ████████████████████ 100

  findings: 6 errors · 10 warnings · 2 info

  Descriptions
    ✖ D002 [get_user] Description of "get_user" is only 12 chars ("Gets a user.").
      ↳ Expand to at least one full sentence: what it does, when to use it, what it returns.
    ...

CI

mcpgrade <target> --json                # machine-readable
mcpgrade <target> --fail-on error       # exit 1 on errors — gate your PRs
mcpgrade <target> --disable S008,N001   # tune rules
mcpgrade rules                          # list all rules

Why

I integrate first-party and third-party MCP connectors into a production AI agent for a living. Most MCP servers fail agents in the same ten ways — none of which show up in a spec compliance check. So I wrote the linter I wished server authors had run before shipping.

mcpgrade vs mcp-lint

Different tools, different questions. mcp-lint checks whether your tool schemas parse correctly across clients (Claude, Cursor, OpenAI strict mode, ...) — syntax-level compatibility. mcpgrade measures whether a model can actually use your tools — description quality, naming confusion, token economics, and live LLM tool-selection accuracy. A server can pass mcp-lint cleanly and still score an F here, and vice versa. They compose well: lint for compatibility, grade for usability. Full side-by-side with concrete outputs: docs/comparison.md.

Roadmap

• v0.1 — static lint engine, 24 rules, A–F scoring
• v0.2 — --eval: LLM-powered live testing — synthetic task generation, blind tool selection, argument validation, refusal accuracy, confusion pairs. Calibrated on real servers (methodology); costs ~$0.05–0.2 per server on Haiku. Bring your own ANTHROPIC_API_KEY, or any OpenAI-compatible endpoint via --eval-base-url (DeepSeek, OpenRouter, ...); --eval-mock runs offline. Respects HTTPS_PROXY.
• v0.3 — GitHub Action, dynamic badges, public leaderboard of popular MCP servers

License

MIT