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.

Related MCP server: MEOK MCP Test MCP

Attack scenarios

Mapping to the OWASP MCP Top 10

Scenarios above line up with the OWASP MCP Top 10 as follows. MCP08 (Lack of Audit and Telemetry) and MCP09 (Shadow MCP Servers) are intentionally out of scope — both describe properties of the deployment (server-side logging discipline, unapproved deployments) rather than a payload a single test server can carry.

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.

Install with Docker

docker build -t bad-mcp .
docker run --rm -p 8971:8971 -v "$(pwd)/data:/data" bad-mcp
# detector connects to:  http://127.0.0.1:8971/mcp

The image's default command runs serve-http bound to 0.0.0.0:8971 inside the container (safe — that address is only reachable via the port you publish) and writes the event log to /data/events.jsonl; mount a host directory at /data to keep it. Override the command to run other subcommands, e.g.:

docker run --rm -v "$(pwd)/data:/data" bad-mcp simulate --out /data/events.jsonl
docker run --rm bad-mcp list

Or with Compose (writes to ./data/events.jsonl on the host):

docker compose up --build

Deploy as a remote MCP server (AWS)

To point a detector at a real "unvetted remote server" instead of 127.0.0.1, terraform/ deploys this same image to AWS App Runner behind a fixed HTTPS URL, gated by a generated shared-secret header.

cd terraform/
cp terraform.tfvars.example terraform.tfvars
terraform init && terraform apply
terraform output mcp_url

See terraform/README.md for prerequisites, cost (roughly $3-10/month depending on usage — no ALB/NAT/VPC in this setup), and teardown. This puts the fixture on the public internet; the shared secret is the access control, so keep it private and terraform destroy when done.

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, command_injection_attempted, credential_field_advertised, secret_exfiltration_attempted, supply_chain_impersonation_present, scope_creep_escalated, missing_authorization_check, unauthorized_action_performed.

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.

Note: scope_creep and rug_pull also interact by design — a schema that silently gains a permission-shaped field is also a hash change, so a naive rug-pull detector correctly (if generically) flags it too. detector.py additionally labels it scope_creep specifically when the new field is one of action/share_with/scope/role/admin, to show how a detector can tell "the payload changed" apart from "the permission surface grew".

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.

License

MIT