MCPSentinel

MCPSentinel

+----------------------------------------------------------------+ | MCPSENTINEL | | Security review for Model Context Protocol servers | | Read-only by default | +----------------------------------------------------------------+

Discover MCP metadata. Triage suspicious intent. Review changes before you trust them.

MCPSentinel is a precision-first security scanner for Model Context Protocol servers. It treats a static rule hit as a candidate, then applies semantic intent analysis before reporting it. This keeps the fast coverage of pattern matching without making every normal-looking fetch or delete tool a noisy vulnerability.

The default judge is an offline, deterministic heuristic—not an LLM. Optional OpenAI review transmits bounded, redacted metadata to OpenAI. Neither mode proves that a server's implementation is safe.

Version scope: v0.8.8. The PyPI badge above shows the published version; install from source if your installed release predates the features here. The M8ven badge concerns the source revision linked on its listing, not this working tree, package provenance, or measured detection accuracy. Read the dated engineering assessment for evidence and remaining gates.

Start in 60 seconds

python -m pip install mcp-guardian-scan

mcpsentinel # safe, no-write onboarding mcpsentinel scan http://localhost:8000/mcp

The first command opens a friendly, copy-pasteable onboarding guide. Interactive terminals get colored panels; json and sarif remain free of decorative text for automation.

The review loop

discover metadata  ->  static candidates --------> semantic triage  -> human review

| ^ | +-> every server instruction (MCP-S001) --------+ v explicitly approve baseline

What you get

• MCP v2 discovery over stdio and Streamable HTTP, negotiating server/discover first and falling back automatically to legacy initialize
• configurable static pattern rules for tool, prompt, resource, resource-template, and server-instruction descriptors, including tool poisoning, shadowing, cross-server, and OAuth confused-deputy signals
• semantic triage: offline heuristic by default, optional OpenAI structured-output judge with bounded fallback; every server-level instruction receives a dedicated MCP-S001 review even without a regex hit
• explicit baseline approval, field-aware descriptor diffs, and stable server identity/protocol drift detection
• protocol-integrity checks that reject duplicate descriptor identities before a baseline can become trusted
• branded Rich terminal, JSON, SARIF, and self-contained HTML risk reports
• allow/deny policy configuration
• explicit, Docker-sandboxed owned-tool validation with no network egress
• GitHub Action and MCP-native scanner interfaces

Static scans are metadata-only. Dynamic invocation is a separate opt-in path described below and never runs from the GitHub Action or MCP-native server.

Install and onboard

Install the published package, then use the MCPSentinel CLI:

python -m pip install mcp-guardian-scan

mcpsentinel

Running mcpsentinel with no command starts a short, no-write terminal onboarding guide. It explains the read-only scan model, gives a copy-pasteable first scan, and keeps OpenAI optional. Use mcpsentinel onboard (or the alias mcpsentinel init) to show it again, or tailor the suggested command without contacting a server:

mcpsentinel onboard --target https://mcp.example.com/mcp

mcpsentinel onboard --target "python -m example_mcp_server" --transport stdio

In an interactive terminal the guide uses colored panels and copy-pasteable commands. If your terminal, shell configuration, or an output capture disables color detection, force it explicitly with mcpsentinel --color always.

The onboarding flow never asks for, stores, or transmits an API key. Use mcpsentinel --help or mcpsentinel scan --help for the complete reference.

For development from source:

python -m venv .venv

. .venv/bin/activate python -m pip install -e '.[dev]'

Scan a server

For a Streamable HTTP server:

mcpsentinel scan http://localhost:8000/mcp

For a stdio server, quote its command as the target:

mcpsentinel scan "python -m example_mcp_server" --transport stdio

Or keep the executable and arguments separate. Arguments beginning with a dash need the --arg=value form:

mcpsentinel scan python --transport stdio --arg=-m --arg=example_mcp_server

Stdio targets run as an untrusted child process. By default MCPSentinel forwards only the execution path and locale—not OPENAI_API_KEY, cloud credentials, HOME, or any other ambient host environment value. Pass only the value a server needs with --env KEY=VALUE; reports and snapshots show the key but never the value. --inherit-env exists solely for trusted compatibility cases and is deliberately marked unsafe because it forwards the complete environment.

Read-only does not mean sandboxed. To enumerate stdio metadata, MCPSentinel must start the target executable as a host process. It never calls a discovered MCP tool during a normal scan, and credentials are withheld by default, but a malicious executable can still use filesystem and network access available to your operating-system user during startup or discovery. Scan only stdio executables you trust to launch locally. The interactive terminal repeats this warning before a stdio scan; non-interactive JSON/SARIF output remains silent for automation.

Example interactive result

The capture below uses MCPSentinel's controlled local test fixture, whose tool metadata is intentionally suspicious. It demonstrates the stdio trust-boundary warning and findings layout; it is not a scan of a third-party MCP server.

Useful options:

# Machine-readable report and CI failure gate

mcpsentinel scan http://localhost:8000/mcp --format sarif --output results.sarif --fail-on high

Visual portfolio-ready report

mcpsentinel scan http://localhost:8000/mcp --format html --output risk-report.html

Use OpenAI's structured-output semantic judge (OPENAI_API_KEY is required)

mcpsentinel scan http://localhost:8000/mcp --judge openai --judge-model gpt-4o-mini

Scan using a repository-local baseline root (it contains baselines/ and judge-cache/)

mcpsentinel scan http://localhost:8000/mcp --baseline-dir .mcpsentinel

After reviewing the scan's displayed fingerprint, rediscover and approve only that exact state

mcpsentinel baseline approve http://localhost:8000/mcp --baseline-dir .mcpsentinel \ --fingerprint sha256:REPLACE_WITH_REVIEWED_FINGERPRINT

--baseline-dir is a root directory: by default it is ~/.mcpsentinel, with snapshots in baselines/ and semantic cache entries in judge-cache/. It also contains a local, mode-0600 HMAC scope key. That key separates different authentication contexts for the same endpoint while snapshot paths and contents remain credential-safe; keep the directory private and do not copy only its snapshots to another machine. Snapshots and cache entries are written atomically with unique temporary files, an fsync, and mode 0600 on POSIX systems.

An ordinary scan never updates a baseline. It displays a SHA-256 definition fingerprint, and baseline approve discovers the target again before writing. Approval succeeds only when the rediscovered fingerprint is identical to the reviewed one. Definition fingerprint v2 and baseline snapshot v5 cover both descriptor state and a stable identity subset: server name, server version, negotiated protocol version, and advertised capability names. A changed, added, or removed descriptor—including server instructions—is surfaced as MCP-B001; an identity/protocol change is surfaced separately as medium-severity MCP-B002. The prior approved snapshot is preserved until an explicit approval.

Two descriptors with the same kind:name identity produce MCP-N002, because a dictionary-shaped baseline cannot represent that catalog unambiguously. Approval is refused until the server returns unique identities. Older baselines require a one-time v5 reapproval. Credential-free legacy snapshots may still be compared conservatively, but a legacy snapshot is never trusted or migrated automatically when the target has URL user-info, a sensitive query key, explicit environment values, credential-looking arguments, or inherited host environment access.

The first scan reports that no approved baseline exists. That is an onboarding state, not a vulnerability finding. Establish a baseline only from a server version and environment you trust.

The risk score is a capped 0–100 weighted sum of severity and semantic confidence. It is a prioritization signal, not a claim that the server is safe or unsafe in isolation.

Semantic judges

--judge heuristic is the default and is fully offline. --judge openai requires OPENAI_API_KEY; --judge auto opts into using OpenAI when that key is present, otherwise it uses the heuristic. The OpenAI judge uses the Python SDK's Responses structured-output API, so an API response cannot bypass the scanner's expected verdict schema. Results are cached by descriptor hash plus a versioned judge/prompt identity in the baseline directory to avoid repeat API charges without retaining verdicts after judging methodology changes.

Each OpenAI judgement uses a 30-second client deadline and at most two SDK retries. Before an OpenAI request, MCPSentinel recursively redacts secret-valued structured fields, then redacts common API keys, bearer credentials, and private keys in text. Prompts are capped at 12,000 characters with field-aware head-and-tail excerpts, so a long descriptor cannot simply hide all final evidence behind filler. Candidate assessment uses a bounded concurrency of four requests. Redaction is defense-in-depth, not a guarantee that arbitrary sensitive meta