mcp-toolguard 0.2.0

Contracts, drift detection and security checks for MCP servers — in CI and in production.

ToolGuard

Contracts, drift detection and security checks for MCP servers — in CI and in production.

Know when an MCP server changes — yours, or the one you depend on.

⚠️ Pre-release. The full toolkit ships before the MCP 2026-07-28 spec lands.

• ✅ mcp-toolguard scan — snapshot an MCP server's tools, schemas, capabilities and descriptions (stdio & streamable HTTP), with security findings
• ✅ mcp-toolguard baseline [--update] — commit a reference snapshot to your repo
• ✅ mcp-toolguard diff — classified diff against the baseline: breaking / compatible / suspicious
• ✅ mcp-toolguard ci — exit codes and Markdown output for any CI, plus spec-version matrix validation (2025-11-25 + 2026-07-28)
• ✅ 15 security rules against tool poisoning, exfiltration and lying annotations
• ✅ A GitHub Action wrapping all of the above: toolguard-io/action@v1

Usage

# Snapshot a server over stdio…
mcp-toolguard scan "python -m my_mcp_server"

# …or over streamable HTTP; --json emits the full canonical snapshot
mcp-toolguard scan https://api.example.com/mcp --json

# Save the reference contract to .toolguard/baseline.json (commit it!)
mcp-toolguard baseline https://api.example.com/mcp

# What changed since the baseline? breaking / compatible / suspicious
mcp-toolguard diff https://api.example.com/mcp

# Gate your CI: fails on breaking changes or spec errors (policy: breaking)
# --policy audit never fails; --policy strict fails on any change
# Also validates against the MCP spec matrix: 2025-11-25 + 2026-07-28 (RC)
mcp-toolguard ci https://api.example.com/mcp --markdown

# Accepting a contract change is explicit and visible in code review:
mcp-toolguard baseline https://api.example.com/mcp --update

Exit codes: 0 ok · 1 policy failure (ci) · 2 operational error.

Security rules

Every scan and ci runs a pack of 15 rules over the snapshot — the text and schemas that reach your model's context:

• TG1xx — tool poisoning / prompt injection: imperative instructions to the model ("ignore previous instructions", "do not tell the user"), hidden <IMPORTANT>-style tags, cross-tool coercion, references to ~/.ssh and other sensitive files, embedded URLs, encoded blobs, invisible characters.
• TG2xx — exfiltration via schemas: credential-shaped input parameters, environment-variable harvesting, conversation harvesting, unconstrained input schemas.
• TG3xx — broad permissions and lying annotations: arbitrary-execution tools, readOnlyHint/destructiveHint contradicted by what the tool says it does, credentials returned in outputs.

In ci, findings already present in the committed baseline are the accepted state; only new findings gate. Policy breaking fails on new high-severity findings; strict fails on any new finding.

Install

uvx mcp-toolguard --version
# or
pip install mcp-toolguard

License

MIT — see LICENSE.