Skip to main content
Glama

mcp-behave

Runtime behavioral auditing and monitoring for Model Context Protocol (MCP) servers.

CI PyPI npm MCP Registry License: MIT PyPI Downloads

npm downloads

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.

mcp-behave demo

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

Or install the Python package:

python -m pip install mcp-behave
mcp-behave --version

An npm package is also available:

npm install -g mcp-behave
mcp-behave --version

About 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_server

You 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-git

By 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_server

The 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 telemetry

Start in monitoring mode:

uvx mcp-behave wrap \
  --server my-server \
  -- python -m my_mcp_server

wrap 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_server

This 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_server

To review a manifest change observed by wrap and approve it into the lockfile:

uvx mcp-behave approve --server my-server

Useful wrap options:

Option

Purpose

--enforce

Enforce lockfile-based tool policy checks. Requires a valid matching entry in mcp-behave.lock.json.

--redact

Replace detected sensitive values in inspected server responses.

--canary TOKEN / --canary-file PATH

Watch for configured canary values in inspected traffic.

--sandbox auto

Request the platform-appropriate sandbox backend.

--no-trace

Disable native runtime tracing and retain protocol-level monitoring.

--no-reverify

Disable periodic synthetic tools/list re-verification.

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

mcp-behave lint manifest.json

Static checks of a manifest or tool-definition JSON without starting a server.

mcp-behave scan-configs

Find MCP servers in supported local client configuration files and inspect configuration risks.

mcp-behave audit-configs

Discover configured servers and run audits against them. This actively launches and exercises targets.

mcp-behave inspect <command>

View a correlated timeline of MCP messages and observed runtime events; can also inspect a prior output directory.

mcp-behave serve

Expose mcp-behave's audit and inspection tools through an MCP server interface.

mcp-behave install / status / uninstall

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

The 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_server

This 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_PRELOAD library when available, with strace as a fallback when installed. A C compiler is needed to build the native library on first use.

  • Remote transports: sse and streamable-http can be used for remote manifest checks, but mcp-behave cannot trace the remote server's local operating-system activity.

  • Untraced mode: --no-trace skips 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_server

A 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 -v

The 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 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
Read-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_configsA
Read-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

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      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