mcp-redteam
Runtime red-team testing for Model Context Protocol (MCP) servers.
mcp-redteam connects to a running MCP server, exercises it with a curated
attack-payload library, and produces evidence you can act on: request/response
transcripts, severity, and reproduction steps for every finding.
It is not a static config linter. Static scanners are useful for catching risky
strings in mcp.json files and tool descriptions. mcp-redteam is the
complementary runtime harness: it talks to the live server and records what the
server actually does.
For authorized security research only. Run this against systems you own or have explicit permission to test.
Why it exists
MCP servers sit between an agent and the outside world. A malicious or compromised server can try to steer the host LLM, mutate tool definitions after approval, or expose resources beyond the boundary a user expected. Those risks are easiest to understand when you have concrete runtime evidence, not just a warning label.
mcp-redteam gives security engineers, agent builders, and platform teams a
repeatable way to probe those behaviors before an MCP server is trusted in a
real workflow.
Theory
MCP as a trust boundary
In a Model Context Protocol deployment, three parties interact: the user, the host (the client application and its LLM), and one or more MCP servers that expose tools, resources, and prompts. The user trusts the host. The host, in turn, treats whatever a server returns — tool descriptions, tool output, resource contents — as trustworthy context and feeds it to the LLM.
That implicit trust is the boundary mcp-redteam interrogates. The protocol was
designed for capability discovery and invocation, not for adversarial isolation:
nothing in the wire format guarantees that a tool's description is benign, that
its output is data rather than instructions, or that its advertised capabilities
stay constant after approval. A server that an agent depends on is therefore
part of the agent's attack surface.
The confused-deputy core
Every probe here is a variation on one classical idea: the confused deputy. The LLM is a privileged actor that acts on behalf of the user, but it cannot reliably distinguish content it should reason about from instructions it should obey. A malicious server exploits that ambiguity to make the deputy (the LLM) act against the principal (the user) using the deputy's own authority.
The four probe families map onto distinct points where that confusion can be induced:
Why runtime evidence
Static analysis can flag a suspicious string in an mcp.json file or a tool
description, but it cannot observe behavior that only appears at runtime: output
that changes with input, a tool catalog that mutates after the first call, or a
resource template that resolves to data outside its intended scope. These are
time-of-check to time-of-use (TOCTOU) and data-dependent behaviors, and the
only sound way to detect them is to drive the live server and record what it
actually does.
mcp-redteam therefore treats a finding as a falsifiable claim backed by a
transcript. Each probe follows the same loop:
payload corpus → mutators → probe drives the server → judge → evidence
- Corpus + mutators. A versioned payload library (
corpus.yaml) is expanded at load time with encodings real attackers use — base64, zero-width characters, and Unicode tag-block smuggling — so detection is not tied to a single literal string. - Probe. Each probe exercises one trust assumption (read descriptions, send adversarial input, re-list after calls, enumerate resources) and captures the full request/response transcript.
- Judge. A pluggable success oracle decides whether a behavior is a finding.
The default judge is heuristic (marker detection, catalog diffing); the
Judgeseam lets an LLM-as-judge backend slot in later without changing probes. - Evidence. Every finding carries severity plus step-by-step reproduction, so a reviewer can replay it rather than trust a label.
This is the project's central thesis: MCP security claims should be reproducible and transcript-backed, not assertions — the same standard a red-team report is held to before anyone acts on it.
Highlights
- Exercises live MCP servers over stdio and streamable HTTP.
- Detects output-side prompt injection, tool poisoning, rug-pull behavior, and over-broad resource templates.
- Captures full request/response transcripts and step-by-step reproduction.
- Generates terminal, JSON, Markdown, and standalone HTML reports.
- Ships with a local web dashboard for demos and triage.
- Includes an intentionally vulnerable MCP server for one-command validation.
- Supports CI gating with severity-based exit codes.
Install
Requires Python 3.11+ and uv.
git clone https://github.com/codezxsWIN/mcp_redteam.git
cd mcp_redteam
uv sync
For local development without cloning from GitHub yet, run uv sync from this
repository root.
Quick start
Scan the bundled vulnerable server over stdio:
uv run mcp-redteam scan stdio:python -m tests.fixtures.vulnerable_server
Write machine- and human-readable reports, and gate CI on severity:
uv run mcp-redteam scan stdio:python -m tests.fixtures.vulnerable_server `
--json findings.json --md report.md --html report.html --severity-threshold high
The process exits non-zero when any finding is at or above
--severity-threshold (default medium), so it drops straight into CI.
Web dashboard
Prefer a point-and-click view for demos or triage? Launch the bundled dashboard:
uv run mcp-redteam serve
Open http://127.0.0.1:8000, enter a target (e.g.
stdio:python -m tests.fixtures.vulnerable_server), pick which probes to run and
a severity threshold, and hit Run scan. Findings render as a severity-colored
table; click any row to expand its full reproduction transcript. The dashboard is
served by Starlette/uvicorn (installed by uv sync). Bind/port are configurable
with --host / --port.
The same styled view is available offline as a standalone file via --html report.html.
Targets
Example run (bundled vulnerable server)
$ uv run mcp-redteam scan stdio:python -m tests.fixtures.vulnerable_server
──────────────── mcp-redteam — stdio: python -m tests.fixtures.vulnerable_server ────────────────
Server: vulnmcp v1.27.1 (stdio) Tools: 3 Resources: 2 Findings: 6
Findings
┌──────────┬──────────────────┬─────────────┬────────────────────────────────────────────┐
│ Severity │ Probe │ Subject │ Title │
├──────────┼──────────────────┼─────────────┼────────────────────────────────────────────┤
│ high │ output_injection │ send_email │ Tool returns attacker-controllable … │
│ high │ output_injection │ summarize │ Tool returns attacker-controllable … │
│ high │ output_injection │ get_weather │ Tool returns attacker-controllable … │
│ high │ tool_poisoning │ send_email │ Tool description carries injection markers │
│ high │ rug_pull │ get_weather │ Tool catalog mutated after use │
│ high │ resource_exfil │ file://{…} │ Over-broad resource template │
└──────────┴──────────────────┴─────────────┴────────────────────────────────────────────┘
Each finding in --json / --md / --html (and in the dashboard) includes the
full request/response transcript
and step-by-step reproduction. For example, the rug_pull finding records the
baseline tools/list, the calls performed, and the post-call tools/list diff
that proves get_weather's description changed after it was trusted.
Probes (v0.1)
Run a subset with --probe:
uv run mcp-redteam scan <target> --probe rug_pull --probe resource_exfil
The payload library lives in mcp_redteam/payloads/corpus.yaml (versioned) and
is expanded at load time by mutators.py (base64, zero-width, unicode tag-block
smuggling). The success judge is heuristic today and sits behind a pluggable
Judge seam (mcp_redteam/judge/) so an LLM-as-judge backend can be added later.
Reports
Use --json, --md, and --html to write artifacts for machines, humans, and
offline review:
uv run mcp-redteam scan stdio:python -m tests.fixtures.vulnerable_server `
--json findings.json `
--md report.md `
--html report.html
The JSON schema is covered by tests, the Markdown report is easy to paste into a ticket, and the HTML report is self-contained for sharing with reviewers.
Threat model
The adversary controls the MCP server. The MCP client is honest, and the user trusts the client's LLM. The goal is to surface server behaviors that let a malicious server (a) influence the LLM, (b) exfiltrate data, or (c) escape intended tool boundaries.
Scope
In scope (v0.1): live stdio + streamable-HTTP servers; the four probes
above; terminal / JSON / Markdown / HTML reporting; a local web dashboard
(serve); CI exit codes; the bundled vulnerable server.
Out of scope (backlog): shadowing / confused_deputy (need multi-server
orchestration), auth_bypass, an LLM-as-judge backend (seam only), SSE
transport, GitHub Action / telemetry, scanning client apps
(Cursor, Claude Desktop), and static config linting (covered by Invariant et al.).
Safety notes
This repository contains intentionally vulnerable fixtures and generated hostile
demo repositories used to validate scanner behavior. Treat directories named
hostile-* as unsafe test material: inspect them only in isolated editor
windows, do not install or run them as normal projects, and do not point agents
with secrets or broad filesystem access at them.
Findings are examples of risky behavior, not proof of exploitation against a third-party system. Always obtain authorization before scanning.
Development
uv run pytest
The test suite spins up the bundled vulnerable server over both stdio and streamable HTTP and asserts every probe fires with a transcript.
Project status
mcp-redteam is an early research tool. The current focus is a small,
well-evidenced probe set for runtime MCP behavior. Contributions that improve
probe accuracy, reporting, transport coverage, or reproducibility are welcome.
