mcp-behave
This server provides MCP security auditing, manifest inspection, and client-config risk scanning tools.
Run a runtime behavioral audit of an MCP server by executing its tools/resources/prompts with canary inputs, capturing filesystem, network, and subprocess activity, and detecting undeclared behavior or manifest rug-pulls.
Inspect an MCP server’s declared capabilities without executing tool actions or tracing syscalls, and check for manifest changes against prior recorded runs.
Scan local AI client configurations to discover configured MCP servers and flag security risks such as hardcoded API keys/tokens, over-privileged root/home mounts, and shell command wrappers.
mcp-behave
Runtime behavioral auditing and monitoring for Model Context Protocol (MCP) servers.
mcp-behave is a CLI-first security tool for checking what an MCP server actually does—not only what its tool descriptions say it can do. It actively exercises a server's advertised capabilities, observes selected runtime activity, checks protocol metadata and responses, and compares behavior with saved baselines.
It also provides mcp-behave wrap, a stdio proxy for monitoring MCP traffic while an AI client uses a server. mcp-behave is CLI-first: it provides terminal, JSON, and SARIF output and does not ship a built-in graphical dashboard.

Why mcp-behave?
An MCP server can advertise a harmless tool while its implementation performs unexpected operations. For example, a tool described as a local document formatter might also read a credential file or attempt an outbound network connection.
mcp-behave compares two views of a server:
Declared behavior: tools, input schemas, annotations, resources, prompts, and metadata exposed over MCP.
Observed behavior: selected file, network, and process activity captured while the server is exercised or monitored.
The goal is to make unexpected behavior visible for review. A clean audit is not proof that a server is safe; it means no covered issue was observed in the tested scenarios.
Related MCP server: Test MCP Server
What it checks
Runtime activity: selected filesystem operations, network connection attempts, and subprocess launches.
MCP metadata: tool definitions, schemas, descriptions, annotations, resources, prompts, and manifest changes.
Content risks: prompt-injection patterns, invisible or bidirectional Unicode characters, terminal escape sequences, and external Markdown/HTML image references in tool output.
Sensitive data: known secret patterns and configured canary tokens in inspected payloads.
Client configuration: hard-coded credentials, broad filesystem mounts, shell wrappers, and unpinned package commands in supported MCP client configuration files.
Findings describe observed behavior and potential risks; they are not automatic accusations of malicious intent.
Install
The simplest option is to run with uvx:
uvx mcp-behave --versionOr install the Python package:
python -m pip install mcp-behave
mcp-behave --versionAn npm package is also available:
npm install -g mcp-behave
mcp-behave --versionAbout the npm package: it is a Node.js launcher for the Python implementation, not a separate JavaScript auditing engine. It requires Node.js 16+ and a Python 3 environment; it uses uvx or pipx when available.
Quick start: audit an MCP server
Pass the command that starts your stdio MCP server:
uvx mcp-behave python -m my_mcp_serverYou can also audit a server launched with npx or uvx:
uvx mcp-behave npx -y @modelcontextprotocol/server-filesystem /path/to/project
uvx mcp-behave uvx mcp-server-gitBy default, mcp-behave initializes an MCP session, discovers the server's tools/resources/prompts, and exercises advertised capabilities with synthesized inputs. It then compares the declared surface with the runtime and content observations.
Important: audits execute server code
An audit is active testing, not passive package inspection. The probe may call tools and read resources/prompts, and those operations can have side effects. Do not run an unfamiliar server against your normal host environment without isolation. Where available, use a disposable Docker or Podman sandbox:
uvx mcp-behave --sandbox auto python -m my_mcp_serverThe audit sandbox defaults to none; --sandbox auto asks mcp-behave to use an available container runtime. Review the target's behavior and permissions before testing it.
Runtime monitoring with wrap
mcp-behave wrap runs between an AI client and a stdio MCP server. The client sends MCP messages to the proxy; the proxy forwards them to the target while monitoring protocol traffic and selected operating-system activity.
AI client <---- stdio / JSON-RPC ----> mcp-behave wrap <---- stdio / JSON-RPC ----> MCP server
|
+-- protocol monitoring
+-- runtime tracing (when available)
+-- policy checks, scanning, and telemetryStart in monitoring mode:
uvx mcp-behave wrap \
--server my-server \
-- python -m my_mcp_serverwrap can also use a multi-server behavioral lockfile, enforce approved tool policies, scan payloads for secrets/canaries, redact detected sensitive values, and apply an optional OS sandbox.
Create and use a behavioral lockfile
Generate or update the multi-server lockfile from an audit:
uvx mcp-behave --lock --server-id my-server python -m my_mcp_serverThis writes mcp-behave.lock.json. Review the generated baseline and commit it to version control. Then run the server through wrap with enforcement enabled:
uvx mcp-behave wrap \
--server my-server \
--lockfile mcp-behave.lock.json \
--enforce \
-- python -m my_mcp_serverTo review a manifest change observed by wrap and approve it into the lockfile:
uvx mcp-behave approve --server my-serverUseful wrap options:
Option | Purpose |
| Enforce lockfile-based tool policy checks. Requires a valid matching entry in |
| Replace detected sensitive values in inspected server responses. |
| Watch for configured canary values in inspected traffic. |
| Request the platform-appropriate sandbox backend. |
| Disable native runtime tracing and retain protocol-level monitoring. |
| Disable periodic synthetic |
wrap is an stdio proxy; it does not turn a remote HTTP MCP connection into a locally traced process.
Other commands
Command | Use it for |
| Static checks of a manifest or tool-definition JSON without starting a server. |
| Find MCP servers in supported local client configuration files and inspect configuration risks. |
| Discover configured servers and run audits against them. This actively launches and exercises targets. |
| View a correlated timeline of MCP messages and observed runtime events; can also inspect a prior output directory. |
| Expose mcp-behave's audit and inspection tools through an MCP server interface. |
| Add, inspect, or remove wrapper entries in supported local AI client configurations. |
CI and machine-readable output
Use JSON or SARIF output for automation and code-scanning workflows:
uvx mcp-behave --json --fail-on high python -m my_mcp_server
uvx mcp-behave --sarif python -m my_mcp_server > mcp-behave.sarifThe default output directory is /tmp/mcp_behave_out. Set --out-dir to choose another location. Exit codes for an audit are 0 for no findings at or above the selected threshold, 3 when the threshold is met, 2 for a tracing/setup failure, and 1 for other errors.
Legacy single-server baseline workflow
The init and check commands maintain the earlier single-server mcp-behave.lock format:
uvx mcp-behave init python -m my_mcp_server
uvx mcp-behave check python -m my_mcp_serverThis is separate from the multi-server mcp-behave.lock.json used by wrap. Keep the two lockfile formats distinct.
Runtime tracing and platform notes
macOS: uses a dynamically injected tracing library (
DYLD_INSERT_LIBRARIES). A C compiler is needed to build it on first use. Some hardened or specially signed interpreters may prevent library injection.Linux: uses a native
LD_PRELOADlibrary when available, withstraceas a fallback when installed. A C compiler is needed to build the native library on first use.Remote transports:
sseandstreamable-httpcan be used for remote manifest checks, but mcp-behave cannot trace the remote server's local operating-system activity.Untraced mode:
--no-traceskips low-level tracing and performs the checks that do not depend on OS telemetry.
Security and coverage limitations
Runtime coverage is not complete syscall tracing. The native interposers observe selected dynamically linked libc calls; direct syscalls, statically linked programs, and other uninstrumented paths may not be visible. The Linux strace backend has different coverage and permission requirements.
Detection also depends on the scenarios exercised. A behavior that only occurs for a particular input, environment, time, or external condition may not appear during a test run. Use multiple probe rounds and adversarial input testing where appropriate:
uvx mcp-behave --probe-rounds 3 --fuzz python -m my_mcp_serverA behavioral baseline records what was observed during a particular set of tests. It can itself be incomplete or unsafe if established from a compromised or insufficiently tested server. Review baseline changes before approving them.
Evaluation
The repository includes benchmark corpora and reports covering paired benign/malicious server fixtures, multi-server authorization scenarios, deterministic runtime-policy tests, and audits of reference MCP servers. The README intentionally keeps detailed tables out of the getting-started path:
These are project-maintained evaluations on specified corpora and fixtures. Results are corpus-specific; they are not independent certification or a guarantee that an arbitrary MCP server is safe.
Documentation
Development
git clone https://github.com/navid72m/mcp-behave.git
cd mcp-behave
python -m pip install -e ".[test]"
pytest -vThe CI workflow runs tests on Linux and macOS. Contributions, bug reports, false-positive reports, and suggestions are welcome through GitHub Issues.
License
MIT. See LICENSE.
Available Tools
3 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_manifestBRead-onlyIdempotent
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
scan_client_configsARead-onlyIdempotent
Scan local AI client configurations (Claude Desktop, Cursor, VS Code, Windsurf, Zed) to discover all configured MCP servers and detect security risks (hardcoded API keys/tokens, over-privileged root/home directory mounts, shell command wrappers).
Inputs: custom_config_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct scope: runtime behavioral auditing with syscall tracing, static manifest inspection without execution, and local client config discovery. The boundaries are explicit in the descriptions, so an agent can reliably choose the right tool.
All three names follow a consistent snake_case verb_noun pattern: audit_server, inspect_manifest, scan_client_configs. The verbs are meaningful and non-overlapping.
Three tools is on the lean side but each covers a genuinely different phase of MCP security review (runtime, manifest, configuration). The scope is well-matched, though one could imagine a fourth tool for reporting or baseline management.
The surface covers the core audit lifecycle: discovering configured servers, inspecting declared capabilities, and exercising them at runtime. Minor gaps exist around explicitly recording/managing prior runs (referenced for rug-pull detection) and exporting findings, which agents can work around.
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 gradedqualityNot gradedmaintenanceA 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