mcp-gauntlet

A linter for the text and schemas your MCP server publishes, plus a live probe and a change detector, for CI.

Concretely, and in the order it does them:

1. Scans every server-authored string an agent will actually see for tool-poisoning and prompt-injection markers, hidden characters and lookalike alphabets — including the surfaces most tools do not read: display titles, output schemas behind a $ref, enum and default values, prompt messages, resource metadata, _meta, and the server's own instructions.
2. Asks tools/list twice and re-scans anything that changed, so a definition that differs between the two answers raises its own finding — and a tool that turns destructive in the second listing is not executed on the strength of the first.
3. Calls what it can safely call: a well-formed call to check the server answers at all, then malformed input to check it rejects what it said was invalid. Read-only tools only, unless you pass --allow-writes.
4. Compares all of that against the last run, so a server that redefines its tools after you approved them is caught.
5. With an API key, drives a live agent through generated tasks — the only way to find out whether your descriptions are good enough to act on.

It fails your build on what it found — a finding with a name and a location — not on a score. And when the gate is wrong, --expect lets you say so without deleting it.

What it is not. Steps 3 and 5 are the only ones that execute anything, and in the CI configuration these docs recommend (--no-agentic), step 3 is all you get: one well-formed call, which stops at the first tool that answers, plus one malformed call per probeable tool. It does not exercise your server's actual behaviour, and it will not tell you your code is correct. It is not a substitute for your integration tests — it sits beside them and reads what your server says.

What it does not catch is written down too: the security checks are pattern-based, and docs/known-gaps.md lists, by class, what has been demonstrated to slip past them — including the most commonly reported real-world poisoning shape. Read it before you treat a clean report as a clearance.

Quickstart

No install, no API key, no clone — this runs the bundled deliberately-malicious demo server and shows what a description scanner cannot see:

uvx mcp-gauntlet run "python -m mcp_gauntlet.fixtures.malicious_server" --no-agentic

Or install it properly:

pip install mcp-gauntlet     # or: uv tool install mcp-gauntlet

# Static + robustness checks only — no API key required
mcp-gauntlet run "python -m mcp_gauntlet.fixtures.good_server" --no-agentic

# Full gauntlet, including the live agent (Groq's free tier works)
export GROQ_API_KEY=gsk_...
mcp-gauntlet run "npx -y @modelcontextprotocol/server-everything"

A .env file in the working directory is read too, if you prefer that to an export.

Pointing it at your own server

This is the case the tool exists for, so it is worth being explicit. Give the interpreter that has your server's dependencies, not a bare python:

# A Python server in a virtualenv — use the venv's interpreter explicitly
mcp-gauntlet run "/path/to/proj/.venv/bin/python -m my_server" --no-agentic
mcp-gauntlet run "C:\path\to\proj\.venv\Scripts\python.exe -m my_server" --no-agentic

# Node
mcp-gauntlet run "node /path/to/proj/dist/index.js" --no-agentic