Mcpgrade

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  --json                # machine-readable
mcpgrade  --fail-on error       # exit 1 on errors — gate your PRs
mcpgrade  --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](docs/comparison.md).

Roadmap

• [x] v0.1 — static lint engine, 24 rules, A–F scoring
• [x] v0.2 — --eval: LLM-powered live testing — synthetic task generation, blind tool selection, argument validation, refusal accuracy, confusion pairs. Calibrated on real servers ([methodology](docs/eval-calibration.md)); 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TengByte
• Source: TengByte/mcpgrade
• License: MIT

Install and usage instructions live in the source repository linked above.