mcpbait
Runs repeated adversarial assessments against OpenAI-compatible API models (e.g., gpt-4o-mini) to measure agent behavior and produce JSON results.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcpbait
Evidence-led adversarial testing for MCP clients and AI agents
mcpbait acts as a hostile MCP server, presents adversarial tools to an agent, and records observable compromise evidence at the protocol boundary.
A real local reference workflow: zero-network doctor, deterministic assessment, retained state and JSONL evidence, status guidance, and a replayable JSON report. The built-in target is intentionally vulnerable.
Why mcpbait exists
An MCP server controls tool names, schemas, descriptions, and results. That makes the server itself part of the agent's trust boundary. A normal prompt-injection scanner or static source review cannot show what a live client actually sends back to that server.
mcpbait measures that boundary directly:
It builds an isolated workspace containing synthetic canaries.
It exposes adversarial MCP tools over stdio or loopback HTTP.
It observes tool calls, canary returns, local beacon requests, and persistence writes.
It renders the resulting event ledger as terminal, JSON, HTML, or SARIF.
No external command-and-control service or DNS canary is required. The default HTTP
transport binds to 127.0.0.1. Installing the package may require network access;
running the built-in demo does not contact an external service.
Related MCP server: TrustHarness
What the verdicts mean
mcpbait reports observations, not hidden model reasoning.
Verdict | Meaning |
| A synthetic secret, loopback beacon, or persistence marker was verified. |
| The agent engaged with the hostile tool, but no compromise proof was observed. |
| The payload was delivered and no hostile engagement was observed. |
| The payload did not reach the agent at the measured boundary. |
| The technique was not executed. |
IGNORED is not proof of refusal: an agent that rejected a payload and an agent that
never parsed it can look identical from the server side. Repeat real-model assessments
and treat the worst observed result as the useful decision signal.
Quick start
Run the safe reference demo
Python 3.11 or newer is required.
uvx mcpbait doctor
uvx mcpbait demo --dir .mcpbait-reference
uvx mcpbait status --dir .mcpbait-referenceThe demo runs all modules against mcpbait's deliberately defenceless reference agent.
Use it to inspect the workflow and report format, not to evaluate a real model. Supplying
--dir keeps a complete state manifest, synthetic workspace, JSONL evidence ledger, and
re-renderable session instead of discarding the reference run.
For a persistent installation:
uv tool install mcpbait
# or: pipx install mcpbaitAssess a desktop MCP client
Use only with systems and accounts you are authorized to test.
# Confirm the installation and local safety boundary without network access.
mcpbait doctor
# Create private synthetic canaries and an isolated decoy workspace.
mcpbait init
# Add the server under a neutral name. Existing configuration is backed up.
mcpbait install --client claude-desktop --as local-system-indexer
# Restart the client and ask it to perform an ordinary workspace task.
# Confirm the workspace and inspect whether evidence has arrived.
mcpbait status
# Render the completed session.
mcpbait report --html assessment.html --json assessment.json
open assessment.html
# Remove only the entry added above.
mcpbait uninstall --client claude-desktop --as local-system-indexerSupported client identifiers are claude-desktop, cursor, windsurf, and cline.
Configuration updates preserve unrelated entries and retain a .bak copy of the state
that existed before mcpbait changed the file.
Threat model and evidence path
┌─────────────────┐ MCP tools/results ┌──────────────────────┐
│ Agent or client │ <──────────────────────────── │ Adversarial server │
│ under test │ ────────────────────────────> │ and event recorder │
└────────┬────────┘ tool arguments └──────────┬───────────┘
│ │
│ reads or writes │ verifies
v v
┌─────────────────┐ ┌──────────────────────┐
│ Isolated decoy │ │ JSONL evidence log │
│ workspace │ │ and reports │
└─────────────────┘ └──────────────────────┘The synthetic workspace, state file, and session logs are written with private file permissions. Shareable reports redact canary values to recognizable prefixes; the raw JSONL session log remains the operator's local evidence source.
Technique coverage
The current release contains 13 modules across the agent intrusion lifecycle.
Phase | Module | MITRE ATLAS | Observable signal |
Access |
| Canary returned in a tool argument | |
Access |
| Hidden directive followed | |
Access |
| Discovery-time directive followed | |
Access |
| Shadow tool selected | |
Influence |
| Sibling tool routing altered | |
Influence |
| Result-borne directive followed | |
Influence |
| Mutated schema invoked | |
Collection |
| Planted credential returned | |
Collection |
| Context returned in a tool call | |
Exfiltration |
| Canary embedded in nested input | |
Exfiltration |
| Loopback image request observed | |
Persistence |
| Standing-instruction marker on disk | |
Social |
| Secret submitted through elicitation |
Detailed payload, verification, and remediation notes live in
docs/techniques/.
Reports and automation
Render one completed session in several formats:
mcpbait report \
--html assessment.html \
--json assessment.json \
--sarif assessment.sarif \
--fail-under 7.5The HTML report is a self-contained black-and-white assessment view with technique
filters, a redacted evidence ledger, and remediation priorities. SARIF output can feed
code-scanning workflows. Exit code 3 indicates that the score fell below the selected
threshold.
Run repeated assessments against an OpenAI-compatible API:
export MCPBAIT_API_KEY='...'
mcpbait assess --model gpt-4o-mini --runs 3 --json result.jsonCompare several configured model IDs without publishing an invented leaderboard:
mcpbait matrix \
--models 'model-a,model-b' \
--runs 3 \
--markdown matrix.md \
--json matrix.jsonStreamable HTTP
Install the optional transport dependency, then bind locally:
pip install 'mcpbait[http]'
mcpbait serve --http --host 127.0.0.1 --port 8731
mcpbait config --http --as docs-search --port 8731The endpoint defaults to http://127.0.0.1:8731/mcp. Captured credential-shaped HTTP
headers are redacted before they are written to disk. Exposing the service beyond
loopback is an operator decision and should be protected like any other security test
infrastructure.
Command reference
Command | Purpose |
| Verify the build and local workspace without network access. |
| Show progress, latest evidence, and the next command. |
| Run the full suite against the local reference agent. |
| Create state, canaries, and the decoy workspace. |
| Print an MCP client configuration block. |
| Add mcpbait to a supported desktop client. |
| Remove the mcpbait entry from that client. |
| Serve over stdio or Streamable HTTP. |
| Run repeated tests against one configured model. |
| Compare repeated results across model IDs. |
| Render terminal, JSON, HTML, and SARIF output. |
| List the modules shipped by the installed build. |
| Generate an offline SVG score badge. |
Every command exposes its exact options through mcpbait <command> --help.
The pre-0.4 mcpbait attack spelling remains available as a hidden compatibility alias.
Container use
The repository includes a Dockerfile and MCP registry manifest:
docker build -t mcpbait .
docker run -i --rm mcpbaitThe container starts the stdio server. Mount a dedicated test directory when you need session artifacts outside the container; do not mount a personal workspace into an adversarial test by default.
Engineering assurance
Tests run on Python 3.11, 3.12, and 3.13 with a 92% coverage floor.
ruff, formatting checks, and strictmypyare blocking CI gates.CodeQL uses the
security-extendedquery suite.GitHub Actions are pinned to commit SHAs and use explicit permissions.
Releases use PyPI Trusted Publishing and generate a CycloneDX SBOM.
State, synthetic workspace files, reports, and raw logs use atomic or private writes according to their sensitivity.
Local development:
git clone https://github.com/jankesec/mcpbait.git
cd mcpbait
uv sync --all-extras --dev
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest -q --covSee CONTRIBUTING.md for module design and contribution guidance,
and SECURITY.md for private vulnerability reporting.
Responsible use
mcpbait is intended for authorized security testing, defensive research, and controlled benchmarking. It creates deceptive tool definitions and synthetic credential material by design. Run it in an isolated test workspace, disclose the test to the system owner, and remove client configuration when the assessment is complete.
License
MIT License. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Security research canary remote MCP server for owned-account testing.
MCP compatibility and transport verification server.
MCP compatibility and transport verification server.
MCP compatibility and transport verification server.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA deliberately insecure MCP server designed as a pentest lab to demonstrate common vulnerabilities in MCP deployments.-
- AlicenseBqualityDmaintenanceEnables deterministic security testing of AI agents that use tools by serving synthetic MCP environments with poisoned data, fake secrets, and privileged actions. Records agent tool calls and evaluates security invariants (e.g., canary leaks, forbidden access, approval binding) without an LLM judge or real systems.8MIT
- FlicenseNot gradedqualityDmaintenanceEnables hands-on exploration of common MCP security vulnerabilities through locally runnable vulnerable and fixed servers with accompanying exploits and a dashboard.1-
- AlicenseNot gradedqualityBmaintenanceEnables defenders to deploy a decoy MCP tool server that records and fingerprints how LLM agents probe, escalate, and persist, without exposing real systems.1MIT