mcp-gauntlet

A regression suite for your MCP server. Run it in CI and it catches what you cannot catch by reading your own code: a payload that only appears when a tool is called, a definition that changes between two tools/list calls, a tool that silently accepts malformed input, a description no agent can act on.

It fails your build on what it found — a finding with a name and a location — not on a score.

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

# A path containing spaces — use SINGLE quotes inside the spec. The spec is parsed
# POSIX-style, so double quotes are consumed by your shell before the tool sees them and
# the path silently splits into extra arguments.
mcp-gauntlet run "C:\Tools\python.exe 'C:\Users\Jane Smith\proj\server.py'" --no-agentic

# A remote server, with auth
mcp-gauntlet run "https://mcp.example.com/mcp" --header "Authorization: Bearer $TOKEN"

Two things that bite people, both worth knowing before they cost you a debugging cycle:

• A bare python is not your python. Under uvx, the gauntlet's own environment comes first on PATH, so python -m my_server runs under its interpreter — which does not have your server's dependencies and fails with an import error that looks like your bug.
• Relative paths resolve from wherever you ran the command, not from your server's directory. Absolute paths avoid the whole question.

The LLM backend is provider-agnostic — any OpenAI-compatible endpoint (Groq by default; also OpenRouter, Together, or a local Ollama / vLLM). Transient 429/5xx responses are retried with bounded backoff, so a free-tier rate limit costs a short wait, not the run — only a truly exhausted quota (a long Retry-After) makes a run inconclusive. Runs are read-only by default: tools that look mutating (by name/description or a self-declared MCP destructiveHint) are excluded unless you pass --allow-writes. That exclusion is a best-effort heuristic, not a guarantee — pair it with read-only credentials or a throwaway environment for untrusted servers. Generated task sets are cached so scores are reproducible across runs.

Bundled good / bad fixture servers make it easy to see the difference:

mcp-gauntlet run "python -m mcp_gauntlet.fixtures.bad_server"   # capped C — tool poisoning
mcp-ga