Mcp-scan: constrain, log and scan your active MCP connections

1 day ago 2

MCP-Scan is a security scanning tool to both statically and dynamically scan and monitor your MCP connections. It checks them for common security vulnerabilities like prompt injections, tool poisoning and cross-origin escalations.

It operates in two main modes which can be used jointly or separately:

mcp-scan scan statically scans all your installed servers for malicious tool descriptions and tools (e.g. tool poisoning attacks, cross-origin escalation, rug pull attacks).

Quickstart →.
mcp-scan proxy continuously monitors your MCP connections in real-time, and can restrict what agent systems can do over MCP (tool call checking, data flow constraints, PII detection, indirect prompt injection etc.).

Quickstart →.

mcp-scan in proxy mode.

Scanning of Claude, Cursor, Windsurf, and other file-based MCP client configurations
Scanning for prompt injection attacks in tools and tool poisoning attacks using Guardrails
Enforce guardrailing policies on MCP tool calls and responses, including PII detection, secrets detection, tool restrictions and entirely custom guardrailing policies.
Audit and log MCP traffic in real-time via mcp-scan proxy
Detect cross-origin escalation attacks (e.g. tool shadowing), and detect and prevent MCP rug pull attacks, i.e. mcp-scan detects changes to MCP tools via hashing

To run a static MCP scan, use the following command:

This will scan your installed servers for security vulnerabilities in tools, prompts, and resources. It will automatically discover a variety of MCP configurations, including Claude, Cursor and Windsurf.

Using mcp-scan proxy, you can monitor, log, and safeguard all MCP traffic on your machine. This allows you to inspect the runtime behavior of agents and tools, and prevent attacks from e.g., untrusted sources (like websites or emails) that may try to exploit your agents. mcp-scan proxy is a dynamic security layer that runs in the background, and continuously monitors your MCP traffic.

You can also add guardrailing rules, to restrict and validate the sequence of tool uses passing through proxy.

For this, create a ~/.mcp-scan/guardrails_config.yml with the following contents:

<client-name>: # your client's shorthand (e.g., cursor, claude, windsurf) <server-name>: # your server's name according to the mcp config (e.g., whatsapp-mcp) guardrails: secrets: block # block calls/results with secrets custom_guardrails: - name: "Filter tool results with 'error'" id: "error_filter_guardrail" action: block # or just 'log' content: | raise "An error was found." if: (msg: ToolOutput) "error" in msg.content

From then on, all calls proxied via mcp-scan proxy will be checked against your configured guardrailing rules for the current client/server.

Custom guardrails are implemented using Invariant Guardrails. To learn more about these rules, see this playground environment and the official documentation.

MCP-Scan scan searches through your configuration files to find MCP server configurations. It connects to these servers and retrieves tool descriptions.

It then scans tool descriptions, both with local checks and by invoking Invariant Guardrailing via an API. For this, tool names and descriptions are shared with invariantlabs.ai. By using MCP-Scan, you agree to the invariantlabs.ai terms of use and privacy policy.

Invariant Labs is collecting data for security research purposes (only about tool descriptions and how they change over time, not your user data). Don't use MCP-scan if you don't want to share your tools. You can run MCP-scan locally by using the --local-only flag. This will only run local checks and will not invoke the Invariant Guardrailing API, however it will not provide as accurate results as it just runs a local LLM-based policy check. This option requires an OPENAI_API_KEY environment variable to be set.

MCP-scan does not store or log any usage data, i.e. the contents and results of your MCP tool calls.

For runtime monitoring using mcp-scan proxy, MCP-Scan can be used as a proxy server. This allows you to monitor and guardrail system-wide MCP traffic in real-time. To do this, mcp-scan temporarily injects a local Invariant Gateway into MCP server configurations, which intercepts and analyzes traffic. After the proxy command exits, Gateway is removed from the configurations.

You can also configure guardrailing rules for the proxy to enforce security policies on the fly. This includes PII detection, secrets detection, tool restrictions, and custom guardrailing policies. Guardrails and proxying operate entirely locally using Guardrails and do not require any external API calls.

MCP-scan provides the following commands:

mcp-scan - Security scanner for Model Context Protocol servers and tools

These options are available for all commands:

--storage-file FILE Path to store scan results and whitelist information (default: ~/.mcp-scan) --base-url URL Base URL for the verification server --verbose Enable detailed logging output --print-errors Show error details and tracebacks --json Output results in JSON format instead of rich text

Scan MCP configurations for security vulnerabilities in tools, prompts, and resources.

mcp-scan [CONFIG_FILE...]

Options:

--checks-per-server NUM Number of checks to perform on each server (default: 1) --server-timeout SECONDS Seconds to wait before timing out server connections (default: 10) --suppress-mcpserver-io BOOL Suppress stdout/stderr from MCP servers (default: True) --local-only BOOL Only run verification locally. Does not run all checks, results will be less accurate (default: False)

Run a proxy server to monitor and guardrail system-wide MCP traffic in real-time. Temporarily injects Gateway into MCP server configurations, to intercept and analyze traffic. Removes Gateway again after the proxy command exits.

mcp-scan proxy [CONFIG_FILE...] [--pretty oneline|compact|full]

Options:

CONFIG_FILE... Path to MCP configuration files to setup for proxying. --pretty oneline|compact|full Pretty print the output in different formats (default: compact)

Print descriptions of tools, prompts, and resources without verification.

mcp-scan inspect [CONFIG_FILE...]

Options:

--server-timeout SECONDS Seconds to wait before timing out server connections (default: 10) --suppress-mcpserver-io BOOL Suppress stdout/stderr from MCP servers (default: True)

Manage the whitelist of approved entities. When no arguments are provided, this command displays the current whitelist.

# View the whitelist mcp-scan whitelist # Add to whitelist mcp-scan whitelist TYPE NAME HASH # Reset the whitelist mcp-scan whitelist --reset

Options:

--reset Reset the entire whitelist --local-only Only update local whitelist, don't contribute to global whitelist

Arguments:

TYPE Type of entity to whitelist: "tool", "prompt", or "resource" NAME Name of the entity to whitelist HASH Hash of the entity to whitelist

Display detailed help information and examples.

# Scan all known MCP configs mcp-scan # Scan a specific config file mcp-scan ~/custom/config.json # Just inspect tools without verification mcp-scan inspect # View whitelisted tools mcp-scan whitelist # Whitelist a tool mcp-scan whitelist tool "add" "a1b2c3..."

We welcome contributions to MCP-Scan. If you have suggestions, bug reports, or feature requests, please open an issue on our GitHub repository.

To run this package from source, follow these steps:

uv run pip install -e . uv run -m src.mcp_scan.cli

Including MCP-scan results in your own project / registry

If you want to include MCP-scan results in your own project or registry, please reach out to the team via [email protected], and we can help you with that. For automated scanning we recommend using the --json flag and parsing the output.

See CHANGELOG.md.

Read Entire Article