warden MCP server
Commit Nov 14, 2026Provides CI-driven integrity gates for MCP servers by pinning tool surfaces and detecting definition drift or dangerous capabilities.
Also known as DataScience-EngineeringExperts/mcp-warden
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is warden MCP?
warden provides CI-driven integrity gates for MCP servers by pinning tool surfaces and detecting definition drift or dangerous capabilities.
Summary generated from the project's README
About warden MCP server
Securing the tool surfaces of MCP servers during continuous integration is what mcp-warden enables for developers and security engineers. It functions as a lockfile system that pins the declared tools, resources, and prompts of a server into a signed warden.lock file. This allows teams to establish a human-approved baseline and automatically detect any definition drift or unauthorized changes to tool schemas.
Users can interact with the system via the mcp-warden-cli using commands like pin, check, and guard. The tool supports both stdio and Streamable HTTP connections, making it compatible with various local and remote setups. It is designed to be integrated directly into CI pipelines through a dedicated GitHub Action, which can fail builds and upload SARIF reports to code scanning tools when a server's surface changes unexpectedly.
Beyond drift detection, the system provides security posture audits to find unpinned supply-chain references or weak authentication. It specifically targets the integrity of metadata such as tool names, descriptions, and input schemas, ensuring that the capabilities an agent uses remain exactly what was originally vetted.
What you can do with it
- 1Pinning a server surfaceAn engineer can create a signed baseline of a server's capabilities to ensure future updates are reviewed.
- 2Auditing authentication postureSecurity teams can scan configurations to identify MCP endpoints that lack proper authentication.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledatascience-engineeringexperts/mcp-warden is public and reachablegithub.com/datascience-engineeringexperts/mcp-warden ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/datascience-engineeringexperts/mcp-warden ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-warden
Last Updated: 2026-11-06
mcp-warden is the lockfile and CI gate for MCP servers: it pins a server's declared
tool/resource/prompt surface into a signed warden.lock, then fails CI when that surface
drifts. pin and check support stdio and Streamable HTTP; guard is stdio-only.
CLI 2.0.0 / schema level 4 locks complete tool annotations and output schemas. Changing
destructiveHint, removing a result schema, or widening its types now triggers drift;
the existing runtime tools/list gate checks these fields against v4 locks too.
Older locks stay readable, but require review and re-pinning for this coverage.
Hints are server claims, not proof of safety, and schemas do not certify content. Release
operators can check production OIDC without uploading via RELEASING.md.
mcp-warden-cli is owned by the TheDataExperts PyPI organization.
The company-repository publisher passed an authentication-only check on 2026-11-06;
no package was uploaded and PyPI remains at 2.2.0. The next normal release must
still prove OIDC upload and provenance; see the publishing status.
The proposed next direction is a protocol-neutral Warden: human-approved tool versions and bounded actions, with untrusted inputs kept separate from authority. The upgrade plan and checkpoint proposal maps prompts, retrieval, code execution, and serverless adapters to existing Agent Trust Kernel work. Those broader checkpoints are proposals, not shipped guarantees.
The opt-in artifact trust foundation adds public-key
verification for the existing kernel activation APIs and trust CLI commands
to prepare unsigned review artifacts and verify external signatures. Keys and
signer roles require an independently protected root pin. This development
feature first ships in the 2.1.0 package. The development
decision receipt foundation adds signed evidence,
governed decisions and recovery ports. Live checkpoint enforcement still requires
an independently protected platform provider and DSE-1076 guard integration.
⚠️ Install
mcp-warden-cli, notmcp-warden. The PyPI namemcp-wardenis an unrelated package by a different author — it is not this project. The correct install ispip install mcp-warden-cli(the CLI command is stillmcp-warden). Or use the GitHub Action / a git-pinned install.
If you already follow the published guidance — pin versions, hash tool definitions, alert on drift — mcp-warden is the deterministic tool that does it.
The mental model (analogy ladder):
package-lock.json/Cargo.lock— a committed, reproducible lock of what you depend on.warden.lockis that, for an MCP server's declared surface.gitleaksin CI — a deterministic, exit-non-zero gate wired into the pipeline.mcp-warden checkis that, for MCP surface drift (and ships the same SARIF → code-scanning integration).Dependabot/ pin-then-review — a human approves an upstream change before it lands.pin --approve+ the drift gate force a human in the loop on any MCP rug-pull.
Scope honesty — mcp-warden is an MCP supply-chain integrity gate, not a full agent firewall. It verifies the declared surface returned by
tools/list/resources/list/prompts/list; it does not defend behavioral attacks (T-BEHAVE) and makes no compliance/regulatory claim. The v0.3guardproxy adds runtime result inspection (ANSI/control escapes, echoed secrets, exfil domains — deterministic, default-block), but definition-integrity is the core job. Read the limits first:docs/THREAT_MODEL.md,docs/THREAT_MODEL_V2.md,docs/GUARD_PROXY_V3.md.
60-second quickstart
Copy-paste runnable against the fixtures shipped in this repo. Requires Python ≥ 3.11.
# 1. Install (from a clone of this repo)
uv venv .venv
uv pip install --python .venv/bin/python -e ".[dev]"
# 2. Zero-config posture scan of every MCP config already on this machine — Claude Code,
# Claude Desktop, Cursor, VS Code, Windsurf, Codex. Static: no spawn, no network.
# Reports weak auth, unpinned npx/uvx launches, and every server with no lock, then
# prints the exact `pin` command for each. (docs/DOCTOR.md)
.venv/bin/mcp-warden doctor
# 3. Pin a server's declared surface and approve it (TOFU baseline) -> writes the lock
.venv/bin/mcp-warden pin python tests/fixtures/clean_server.py \
--approve --approver you@example.com \
--lock warden.lock
# 4. Check the same surface against the lock -> exit 0 (no drift)
.venv/bin/mcp-warden check python tests/fixtures/clean_server.py --lock warden.lock
# 5. Prove the gate fires: a rug-pulled server drifts -> DRIFT DETECTED, exit 1
.venv/bin/mcp-warden check python tests/fixtures/mutated_server.py --lock warden.lock
For an already-running Streamable HTTP server, use --url instead of a server command:
.venv/bin/mcp-warden pin --url https://example.com/mcp --approve --approver you@example.com --lock warden.lock
.venv/bin/mcp-warden check --url https://example.com/mcp --lock warden.lock
Then wire it into CI with the official GitHub Action (point server-cmd at your server's launch argv, commit warden.lock):
# .github/workflows/mcp-integrity.yml
permissions:
contents: read
security-events: write # only needed when upload-sarif: true (the default)
jobs:
mcp-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: DataScience-EngineeringExperts/mcp-warden@v0
with:
server-cmd: "node ./build/index.js"
lock: "warden.lock"
The Action runs check, fails the build on any drift, and (by default) uploads a
SARIF report to GitHub code scanning. Full input table is in
GitHub Action below.
Where mcp-warden fits — complements, not substitutes
MCP security splits into three different jobs that run at different times. They are complementary layers; running mcp-warden alongside a scanner and/or a gateway closes gaps none of them cover alone.
| Category | Example | When it runs | What it locks down | Use it when… |
|---|---|---|---|---|
| Static tool-poisoning scanner | mcp-scan | pin-time / pre-flight | suspicious content in tool definitions (injection-style descriptions, known-bad patterns) | you want to catch a poisoned definition the first time you see it |
| Runtime gateway / proxy | ContextForge, Lunar MCPX, TrueFoundry, Docker MCP Gateway | every live request | runtime mediation — auth, rate limits, request/response policy on calls in flight | you need to mediate or police live traffic between agent and server |
| Lockfile + CI gate | mcp-warden | CI / pre-commit | drift — the declared surface changing after a human approved it (rug-pull / silent redefinition) | you want a reproducible, human-approved baseline that fails the build when the surface changes |
| Config + deploy gates | mcp-warden (auth audit, deploy-gate) |
CI / pre-commit | posture — remote MCP endpoints with no auth or credentials pasted into config; agent deploys whose evals regressed or whose guardrails were switched off | you want the deploy blocked, not just reported, when the declared safety bar isn't met |
mcp-warden does not replace a scanner or a gateway — it adds the missing drift gate: a signed baseline plus a deterministic CI check that the surface you approved is the surface you still run.
The common thread across all four commands is that they block. The loudest
complaint about agents in production is that they are insecure by default and
nothing stops a bad configuration or a regressed deploy from shipping — plenty of
tools report, very few return a non-zero exit code that a pipeline must answer
for. check blocks on surface drift, auth audit blocks on weak MCP auth
posture, and deploy-gate blocks an agent deploy whose evals, guardrails,
budget, or human approval don't meet the declared bar. All three fail closed:
unreadable or missing input is a failure, never a silent pass. See
docs/AGENT_GATES.md.
For the full, sourced breakdown of how these layers complement each other and when to use which, see the comparison page on the docs site.
Who it's for
Adoption compounds the way package-lock.json did — authors adopt, consumers benefit
automatically — so the use cases are sequenced by leverage:
- MCP server author (flagship). Pin your own server's surface, commit
warden.lock, fail any PR that alters it without re-approval, and ship the signed lock alongside releases as a badge of trust — you own the server + CI, so no auth/availability friction. - Server consumer / app team. Pin a third-party server you depend on; CI (or the pre-commit hook) fails when upstream silently redefines its surface — the core rug-pull defense.
- Security / platform engineer. Run the Action
across a fleet; SARIF → code scanning; signed locks = auditable human-approval evidence.
Add
auth auditto catch MCP endpoints configured without auth or with credentials committed into config, anddeploy-gateto make the agent safety bar a build failure rather than a dashboard nobody reads. - Incident responder / auditor.
inspectan offline trace andwarden diffa suspect lock against a known-good baseline — no live server required. - Agent-framework integrator (post-launch). Enforce that only warden-locked servers register in a LangGraph-style orchestrator — one integration locks an entire downstream ecosystem.
What it does
mcp-warden operates entirely on definitions — the (name, description, inputSchema) metadata returned by tools/list, resources/list, and
prompts/list — never on runtime tool behavior or results.
| Threat class | Control |
|---|---|
Definition drift / rug-pull (MCP-DRIFT) |
check re-captures and diffs the surface vs warden.lock; tool inputSchema changes are structurally classified (required dropped, enum widened/removed, type broadened, constraint relaxed, additionalProperties opened → WRD-DRIFT-SCHEMA-*) rather than flagged as one opaque change; any drift fails CI |
Dangerous capability surface (MCP-CAPSURF) |
Deterministic WRD-CAP-* static checks (shell/exec, fs-write, fs-read, http, sql) |
Secret leakage in definitions (MCP-SECRET) |
WRD-SEC-* regex + entropy checks; snippets are always redacted |
Unpinned supply-chain refs (MCP-SUPPLY) |
WRD-SUP-* flags unpinned npx/uvx/pip, latest, and `curl |
Poisoned tool results (T-RESULT, v0.2/v0.3) |
guard/inspect run the WRD-RES-* catalog on tool results: ANSI/control escapes, echoed secrets, exfil domains (deterministic BLOCK — default-on in v0.3), curated injection phrases (fuzzy MONITOR, opt-in) |
Reproducibility is the core guarantee: canonicalization is RFC 8785 (JCS) +
SHA-256 (sha256:<hex>), so pin and check agree byte-for-byte. The v0.2
result-inspection catalog is defined once and run identically by guard (live) and
inspect (offline).
Install
Requires Python ≥ 3.11.
⚠️ On PyPI the distribution name is
mcp-warden-cli, notmcp-warden— that name belongs to an unrelated package. The CLI command staysmcp-warden.
# from PyPI (distribution name `mcp-warden-cli`):
pip install mcp-warden-cli
# the CLI is then available as:
mcp-warden --help
# or from a clone of this repo (for development):
uv venv .venv
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/mcp-warden --help
Runtime dependencies: mcp (official MCP Python SDK), rfc8785, pydantic,
typer, rich, pyyaml, anyio.
TLS trust anchor for
--urlcapture. With themcp2.x SDK, HTTP goes throughhttpx2, which verifies server certificates against the OS trust store (viatruststore) rather than Python's bundledcertifiset. Private/corporate CAs installed in the OS now work; a root removed from the OS store is now rejected. Inherited from the SDK; not configurable from the CLI. See CHANGELOG.
TypeScript verifier — @mcp-warden/lock (zero dependencies)
The lock format is vendor-neutral (docs/SPEC.md), and the ecosystem's
servers are mostly Node. packages/lock-ts is a verify-only
TypeScript implementation with no runtime dependencies and no MCP SDK: hand it a
warden.lock and the surface you observed, get back the same drift verdict as the CLI.
Both implementations pass the shared conformance corpus under
vectors/ byte-for-byte in CI.
import { verify } from "@mcp-warden/lock";
const { ok, findings } = verify(lockJson, { command: "node", args: ["./build/index.js"], tools, resources, prompts });
if (!ok) { console.error(findings); process.exit(1); }
The pin / check CI demo
mcp-warden ships two fixture MCP servers under tests/fixtures/ — a clean one
and a mutated (rug-pulled) one — so the whole gate can be demonstrated end to
end without touching a third-party server:
# 1. Pin the clean server's surface (TOFU baseline) -> writes warden.lock
.venv/bin/mcp-warden pin python tests/fixtures/clean_server.py \
--approve --approver ci-bot@example.invalid
# 2. The upstream server is rug-pulled. Re-check against it.
.venv/bin/mcp-warden check python tests/fixtures/mutated_server.py
# -> DRIFT DETECTED, writes SARIF, EXITS NON-ZERO (fails the build)
Full walkthrough — every drift class, the SARIF/JSONL shapes, the structural
inputSchema diffing, and the Action wiring — lives in
docs/PIN_CHECK_DEMO.md.
CI usage — drop-in gate for your own repo
Three steps to add mcp-warden as a CI integrity gate:
1. Pin once (run locally, commit the result):
pip install mcp-warden-cli # PyPI dist name is `mcp-warden-cli`; the command is `mcp-warden`
# Pin your server and record an approval
mcp-warden pin node ./build/index.js \
--approve --approver you@example.com \
--lock warden.lock
git add warden.lock && git commit -m "chore: pin MCP surface baseline"
2. Add the check step to your workflow (.github/workflows/integrity-gate.yml):
- name: Install mcp-warden
run: pip install mcp-warden-cli # PyPI dist `mcp-warden-cli`; CLI command `mcp-warden`
- name: MCP integrity gate (pass path — exits 0 when surface matches lock)
run: |
mcp-warden check node ./build/index.js \
--lock warden.lock \
--sarif warden.sarif
- name: Upload SARIF
if: always()
uses: actions/upload-artifact@v6
with:
name: mcp-warden-sarif
path: warden.sarif
3. On any upstream rug-pull, mcp-warden check exits non-zero and the build
fails before the drifted server reaches your agents. Re-pin only after a human
reviews and approves the new surface.
This repo ships a live demo of this pattern in
.github/workflows/integrity-gate.yml: the "pass path" step checks the clean fixture (exits 0) and the "blocking proof" step checks the mutated fixture (exits 1, inverted to green) to show both sides of the gate on every CI run.
pre-commit hook — the local pre-CI gate
mcp-warden ships a pre-commit hook so the same drift
verdict runs locally on every commit, catching a rug-pulled MCP surface before it
ever reaches CI. The hook reuses the identical capture → checks → drift path as
mcp-warden check, so a local pass/fail can never disagree with CI.
Add this to your .pre-commit-config.yaml (a complete, copy-pasteable example):
repos:
- repo: https://github.com/DataScience-EngineeringExperts/mcp-warden
rev: v1.0.1 # pin to a release tag (supply-chain hygiene)
hooks:
- id: mcp-warden-check
# Everything after `--` is your MCP server launch argv.
# The `--lock` path is resolved relative to your git repo root.
args: [--lock, warden.lock, --, node, ./build/index.js]
Then pre-commit install once. The hook will re-capture your server's surface on
every commit and block the commit on drift (exit 1) until you review and re-pin.
The -- separator (required)
pre-commit is file-triggered, but mcp-warden check takes an MCP server launch
argv, not staged files (the hook sets pass_filenames: false). You tell the hook
where your server command begins with the -- separator: everything after -- is
launched as the server. Without it the hook exits 2 with guidance.
Behavior (clean / drift / server-unavailable)
| Situation | Default (non-strict) | --strict |
|---|---|---|
Surface matches warden.lock |
exit 0 (commit proceeds) | exit 0 |
Drift vs warden.lock |
exit 1 (commit blocked) | exit 1 (commit blocked) |
warden.lock missing / invalid |
exit 2 (commit blocked) | exit 2 |
| Server can't spawn / times out | exit 0 + stderr WARNING (commit proceeds) | exit 2 (commit blocked) |
The default tolerates a locally unspawnable server (a teammate without the right
runtime installed should not be blocked from committing) — drift always blocks in
both modes, only infra-failure handling differs. CI stays strict (it can always
spawn the server), so the drift verdict is identical everywhere. Add --strict to
args: to fail closed locally too.
Opt-outs for slow servers
Spawning the server on every commit adds latency. Teams that find this too slow can run the gate only on push:
- id: mcp-warden-check
stages: [pre-push] # run on `git push`, not every commit
args: [--lock, warden.lock, --, node, ./build/index.js]
…or skip it ad-hoc for a single commit with SKIP=mcp-warden-check git commit ....
warden MCP questions
What is the difference between mcp-warden and a runtime gateway?
mcp-warden is a lockfile and CI gate that verifies the declared tool/resource/prompt surface to prevent definition drift, whereas a runtime gateway mediates live traffic and requests in flight.
Can mcp-warden detect changes in tool schemas?
Yes, it performs structural classification of schema changes, such as when required fields are dropped, enums are widened, or types are broadened.