bad-mcp

A small, extensible harness for building test MCP servers that reproduce common MCP attack patterns, so you can measure whether your detector catches them. Built on the official MCP Python SDK (mcp 2.x).

Serves over Streamable HTTP (point a detector at a URL — the realistic "unvetted remote server" case) or stdio, and can also emit an event log offline with no client at all.

Authorized testing only. This is a detection fixture, not a working attack. Run it in an isolated environment dedicated to evaluating your own tooling.

Safety model

Every scenario is deliberately inert:

• Injection / poisoning strings are realistic (so your detector has real signal to match), but the runtime behaviour is harmless: tools return canned text.
• The only side effect a "successful" attack produces is appending a line to a local sink.log — a stand-in for exfiltration that touches nothing sensitive and never leaves the machine.
• All referenced secrets are canaries (~/.bad-mcp/canary_secret, CANARY-TOKEN-...). No real files are read; there is no network egress.
• ssrf_discovery's internal targets (169.254.169.254, 127.0.0.1:8080, 10.0.0.5) are advertised only in a fake discovery document. Nothing in this repo ever issues a request to them — verify with grep -rn "169.254.169.254" . and confirm every hit is a string literal, not an argument to httpx/requests/urllib/socket.

Attack scenarios

name	pattern
benign_control	clean tools — use it to measure false positives
rug_pull	tool is benign at approval time, then its description/schema silently mutates and a tools/list_changed notification is sent
description_poisoning	tool descriptions carry hidden instructions: imperative overrides, HTML-comment smuggling, invisible Unicode-Tag smuggling, fake "SYSTEM:" directives
tool_shadowing	duplicate tool names in one manifest, plus a tool impersonating a trusted server's tool and redirecting it
prompt_injection	manifest stays clean; the injection instead rides in a tool result (read_ticket) and a notification (get_notification) — probes detectors that only scan descriptions
ssrf_discovery	an OAuth/OIDC discovery document (.well-known/oauth-authorization-server, .well-known/openid-configuration) points authorization_endpoint / token_endpoint / jwks_uri at internal/link-local/cloud-metadata addresses — advertised only, never fetched by this fixture
data_exfiltration	a benign-looking tool's schema asks for excessive up-front context (full_context, environment, ...), plus a tool that advertises over-broad permissions (admin_tool)

Install

Requires Python 3.10+ (the mcp SDK's minimum).

python3.10 -m venv venv && . venv/bin/activate
pip install -e .

This installs the repo as the bad_mcp package (see pyproject.toml), which is what makes python -m bad_mcp.cli below work.

Use

List scenarios:

python -m bad_mcp.cli list

Produce an event log offline (no MCP client needed — best for iterating on a static detector):

python -m bad_mcp.cli simulate --out events.jsonl
python detector.py events.jsonl

Run a live remote server over Streamable HTTP and point your detector's "MCP server URL" input at it (this is the realistic setup — an unvetted remote MCP server):

python -m bad_mcp.cli serve-http --port 8971 --out events.jsonl
# detector connects to:  http://127.0.0.1:8971/mcp

The MCP endpoint is mounted at /mcp by default (--path to change). Your detector connects like any MCP client and will observe the rug-pull change mid-session, the poisoned descriptions, and the shadowed/duplicate tools — while the harness records the ground truth to events.jsonl for scoring.

Remote access from another host is off by default (DNS-rebinding protection). To allow it in an isolated test network:

# bind publicly and permit a specific Host header
python -m bad_mcp.cli serve-http --host 0.0.0.0 --port 8971 \
  --allow-host lab-box:8971 --out events.jsonl

# or, for a throwaway isolated net, skip the Host check entirely
python -m bad_mcp.cli serve-http --host 0.0.0.0 \
  --insecure-disable-host-check --out events.jsonl

ssrf_discovery only serves its discovery document over HTTP mode, at the two .well-known paths below (offline simulate also renders it once, as evidence, without an HTTP server):

python -m bad_mcp.cli serve-http --scenarios ssrf_discovery --port 8971 --out events.jsonl &
curl -s http://127.0.0.1:8971/.well-known/oauth-authorization-server

There is also a local stdio mode for driving with a stdio MCP client:

python -m bad_mcp.cli serve --scenarios rug_pull,tool_shadowing --out events.jsonl

Pick scenarios and the rug-pull trigger:

python -m bad_mcp.cli simulate \
  --scenarios benign_control,rug_pull --trigger after_call --out events.jsonl

Event log (JSONL)

One JSON object per line. Two categories share the stream:

• evidence (ground_truth: false) — what a detector is allowed to see:
  • manifest_snapshot — the tool list served on each list_tools, with per-tool desc_sha / input_schema_sha / raw input_schema (diff the hashes across snapshots to catch rug-pulls; scan input_schema for excessive-context parameter names).
  • tool_call — a tool invocation with its arguments.
  • tool_result — the text a tool call actually returned, logged for every call so runtime-only injections (not just poisoned manifests) are visible to an offline detector.
  • notification — e.g. tools/list_changed, or notifications/message carrying an injected instruction.
  • discovery_document — the OAuth/OIDC .well-known document served (or rendered offline), with its endpoints.
• ground truth (ground_truth: true) — labels for scoring: rug_pull_activated, poisoned_tool_present, duplicate_tool_name, shadow_impersonation, exfil_simulated, injected_result_served, injected_notification_sent, ssrf_discovery_served, context_exfiltration, excessive_scope_advertised.

detector.py is a baseline detector: it raises findings from evidence only, then scores itself against the ground-truth labels. Replace it with your own tool and reuse the scoring harness.

Note: tool_shadowing and rug_pull interact by design. Two tools sharing a name make a naive "hash changed since last snapshot" heuristic report a spurious rug-pull on that name — a useful reminder to key rug-pull detection on stable tool identity, not name alone.

Note: prompt_injection's notification variant (get_notification) calls ServerSession.send_log_message, the SDK's logging-notification API. In mcp 2.x this capability is deprecated and delivery is per-request opt-in (a real client has to have asked for it), so whether the notification actually reaches a live client varies. Ground truth and the notification evidence record are emitted by the scenario unconditionally either way — the event log, not the wire, is what a detector is scored against.

Extending

Add a subclass of Scenario in scenarios.py and register it in REGISTRY:

class MyScenario(Scenario):
    name = "my_attack"
    def tools(self, state):
        return [types.Tool(name="...", description="...", inputSchema={...})]
    async def on_call(self, name, arguments, ctx, state):
        return [types.TextContent(type="text", text="...")]

Emit a ground-truth label whenever your attack actually fires (see self._label_once(...) and self.events.emit(..., ground_truth=True)) so it shows up in scoring.