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~/.sshand 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/destructiveHintcontradicted 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.
Metadata
Release files for mcp-toolguard 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_toolguard-0.2.0.tar.gz | 92.2 kB | Without provenance | Details for mcp_toolguard-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_toolguard-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_toolguard-0.2.0-py3-none-any.whl |
Total release size: 116.9 kB
Release files / mcp_toolguard-0.2.0.tar.gz
| Download URL | mcp_toolguard-0.2.0.tar.gz |
|---|---|
| Size | 92.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86e1ceb52bfbd6611f5fee900952d151c1674fd7f0d223ba7212ad61edb4a950
|
|
BLAKE2b-256 checksum How to use checksums |
b509d0ef05b30bd5df1d516bde623e757d5b5a09e9f26a987a8d59ce0b81551c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mcp_toolguard-0.2.0-py3-none-any.whl
| Download URL | mcp_toolguard-0.2.0-py3-none-any.whl |
|---|---|
| Size | 24.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
721b4beb4809583b44f7bed79c0a77049683063343191ba373303c84dc4abd0c
|
|
BLAKE2b-256 checksum How to use checksums |
0ecaf96e108de610b61d71fb5cc9b52485141a4793b510889bdd6b401d0aa705
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mcp-toolguard 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.