mcpvitals 0.1.0

Vital signs for your MCP servers: health score, token cost, tool-confusion, migration readiness.

mcpvitals

Vital signs for your MCP servers. One command gives you a health score, plus the checks nobody else runs.

[!NOTE] An audit of ~1,850 public MCP servers found 52% abandoned and only 17% production-ready, and a separate benchmark traced 56.7% of agent failures to tool misuse (wrong tool, bad arguments). Registries have no health signal, so a broken server looks identical to a good one. mcpvitals is the checkup.

60-second start

No install. Point it at any MCP server (a stdio command or an http url):

uvx mcpvitals check "npx -y @your/mcp-server"

mcp health: 40 (F)

  x MV020 [run_sql] tool 'run_sql' appears to contain a hard-coded secret
      -> never ship keys in tool metadata; use env vars
  x MV022 [run_sql] description contains model-directed instructions (poisoning surface)
      -> tool descriptions should describe, not instruct the model
  ! MV030 [run_sql] tool 'run_sql' costs ~410 tokens to expose
      -> trim the description/schema; it inflates every request
  ! MV040 tools 'get_user' and 'fetch_user' are 0.91 similar; agents may pick the wrong one
      -> differentiate names/descriptions or merge them
  i MV050 protocol 2025-03-26 predates the 2026-07-28 stateless spec

What it checks

Most linters stop at basic conformance. mcpvitals runs those, plus four things no other tool does:

Area	What it catches
Conformance	empty tool descriptions, duplicate tool names, malformed schemas
Reliability	parameters with no required list, untyped params, error-path gaps
Security hygiene	secrets in tool metadata, over-broad tools (run_sql, exec), model-directed instructions in descriptions (the tool-poisoning surface)
Token cost	how many tokens each tool burns in the context window, and the total cost to connect the server
Tool confusion	pairs of tools an agent will mix up, predicted from name/description overlap before it happens in production
Migration readiness	what breaks under the 2026-07-28 stateless spec

Every check is a pure function scored deterministically. Run mcpvitals check --json for machine output.

Add the health badge to your README

mcpvitals emits a shareable badge so a good score is visible at a glance:

mcpvitals check "npx your-server" --badge badge.svg

Or use the shields.io endpoint output to keep it live.

Use it in CI

Gate your server on every push with the bundled GitHub Action:

- uses: ContextJet-ai/mcpvitals@v0
  with:
    target: "python -m your_server"
    strict: "true"   # fail the build on any error-level finding

Track and monitor (not just a one-shot check)

Pin a server's tools and get alerted when they change. This catches rug-pulls, where a server you already approved silently mutates a tool's schema or description after the fact:

mcpvitals watch "npx your-server"           # pins tools to mcp.lock
mcpvitals watch "npx your-server" --check    # re-run in CI; fails if a pinned tool changed

Probe a running server for live health (uptime and latency):

mcpvitals monitor "https://your-server/mcp" --count 5
# probe 1/5: up 210ms ... uptime 100.0%  avg 207ms

Why this exists

The MCP ecosystem grew faster than the tooling around it. There are thousands of servers and no standard way to tell whether one is any good, safe, or cheap to run. mcpvitals gives authors a one-command checkup before they publish, and gives everyone else a way to vet a server before they trust it.

Built by ContextJet.ai. MIT licensed. Contributions welcome, see CONTRIBUTING.md.