MCP Zero Trust Layer

Website · PyPI · GHCR image · Documentation · Release 0.6.0

MCP Zero Trust Layer, usually shortened to MCPZT, is an open-source and self-hosted security layer for MCP servers. It sits between an MCP client and one or more real MCP servers, then decides what the client can discover, call, send, receive, approve and audit.

Developers and platform teams can enforce policies in front of existing MCP servers. Destination-signed receipts additionally require a cooperating destination; external checks require a scope-specific adapter, separate observer keys and explicit trust configuration.

MCP client / agent
  |
  v
MCP Zero Trust Layer
  |
  |  identity
  |  policy
  |  argument validators
  |  human approvals
  |  output enforcement
  |  audit
  v
real MCP server
  |
  v
database / repository / filesystem / CRM / payment API / internal system

This README is the public practical entry point: what the project does, how to run it, how to configure it, and how to reason about common policy patterns. It intentionally avoids linking to internal planning material so the published package stays focused on usage, operations and security.

The Short Version

An MCP server can expose very powerful capabilities. A read tool such as search_issues can expose sensitive data, while tools such as merge_pull_request, delete_repository, run_sql, send_email, read_secret or create_refund may have real operational impact. If a client can connect directly to the MCP server, the client may be able to list and call more tools than the user or organization intended.

MCPZT adds a policy layer in front of that server. It can hide capabilities from tools/list, block calls before they reach the upstream, validate arguments, require human approval for high-risk actions, redact sensitive output, and write audit logs explaining every important decision.

The important design point is that MCPZT is not a SaaS requirement. It runs locally, in Docker, in CI, as an internal gateway, as a sidecar, or as a stdio wrapper around command-based MCP servers. Configuration is plain YAML, so it can be reviewed in pull requests and versioned with the project it protects.

Status

Current release: 0.6.0, within the 0.x developer-preview line. Use mcpzt version to confirm your installed version. PyPI publishes the Python package; GHCR publishes :0.6.0, the moving :0.6 tag and :latest. Pin a release tag or image digest for repeatable deployments.

The core path is implemented. The package has a CLI, YAML config validation, HTTP proxy mode, stdio wrapper mode, multi-MCP routing, policy evaluation, policy explanation, policy coverage analysis, parameter-level controls, validators, approvals, a self-hosted approval UI, file and SQLite approval storage, output enforcement, capability discovery, onboarding config generation, deterministic scanning, searchable audit logs with hash-chain verification, Prometheus metrics, authentication modes, secret references, client config generation, examples, deployment recipes, Docker packaging and PyPI-ready build metadata.

The HTTP runtime supports MCP Streamable HTTP POST with JSON responses. GET SSE streams are not implemented in this release; the endpoint returns HTTP 405 for GET, which is allowed when a server does not offer an SSE stream. Request-scoped upstream SSE passthrough is intentionally left for a later release because streaming needs a separate security design.

Security hardening is already part of the preview. Production configs reject fail-open dry_run by default, require default deny, require a public base URL or trusted hosts, and require issuer/audience for JWT and OIDC. Shared-key auth does not trust caller-supplied identity headers unless explicitly configured. Request and upstream response sizes are bounded. Upstream error bodies are truncated and redacted. Output policies apply to JSON-RPC result and error payloads. Approvals are single use and the approval UI authenticates decisions and enforces separation of duties. The audit chain can be keyed with an HMAC secret. Output redaction can target values inside text with redact_patterns. Approval decisions are auditable. Production disables FastAPI docs and OpenAPI routes.

CI enforces 100% line coverage, ruff and mypy on Python 3.11–3.14. Coverage does not prove security or an external effect; see the tested cases and remaining limitations.

Why This Project Exists

MCP makes it easy for agents and AI applications to reach real systems. That is the point, and it is powerful. The risk is that many MCP servers are created as local developer tools first, then later connected to systems that deserve more careful authorization. A filesystem MCP may move from reading a scratch directory to reading a repository. A database MCP may move from exploring a sample database to touching production-like data. A GitHub MCP may expose both search and merge operations.

Traditional security controls still matter. OAuth can identify a user or client. Firewalls can restrict network access. Upstream credentials can be scoped. None of that automatically answers MCP-specific questions such as "should this agent see this tool?", "is this SQL query read-only?", "does this tool call need approval?", "did a new tool appear in the upstream?", or "should this returned customer email be redacted before the model sees it?".

MCPZT is built for that missing layer. It treats every MCP interaction as something to evaluate. It understands MCP methods such as tools/list, tools/call, resources/list, resources/read, prompts/list and prompts/get, and it maps those messages into a consistent policy context.

The result is a boring but useful control point. Boring is good here. You want a deterministic layer that can explain why it allowed a call, why it denied a call, why it created an approval, and whether the upstream server was actually contacted.

Documentation: guide index, 0.6.0 upgrade and evidence operations, and executable examples.

0.6.0 external checks and destination receipts

Read-only external checks now contrast a destination's signed claim with a configured source. V2 exports preserve the original receipt and a chain of observer reports, including contradictions and later state changes. The first adapter queries Stripe test-mode refund status; it never creates or retries a refund. Offline verification authenticates the observer's report, not a provider signature or independently proven execution.

Run mcpzt evidence check-demo --directory /tmp/mcpzt-check-demo for a reproducible signed-lie/timeout example with a simulated provider. See external checks, trust boundaries and sandbox setup for the contract, cases and CLI instructions. A live sandbox check requires your configured credentials and an existing bound operation.

Opt-in destination-signed receipts now bind an authorization, tool request and result. The gateway verifies configured signing authorities before filtering output, persists attempts with SQLite approval consumption, and supports read-only reconciliation after a lost response. mcpzt evidence demo --directory /tmp/mcpzt-receipts-demo runs a complete local refund-ledger example; mcpzt evidence verify checks exported commitments offline.

This confirms a statement by a trusted destination within its configured scope, not arbitrary external execution. Upstreams must implement the receipt contract. The reference demo changes a local SQLite ledger and moves no money. See the evidence profile for configuration, signed bytes, idempotency, migration and limits.

Compatibility and upgrade boundary

Read the supported runtime profile before upgrading. The 0.4.0 hardening fixed approval/audit concurrency and enforcement gaps, isolated authenticated HTTP sessions, and invalidated old approvals without its request binding. HTTP upstreams must return JSON. Stdio is a bounded POSIX serial profile; server-initiated messages are rejected explicitly. Gateway observations alone do not provide independent proof of downstream execution. In 0.6.0 evidence remains off by default; enabling it requires a shared private approvals/evidence SQLite database and fresh approvals. Ambiguous duplicate-key JSON and explicit nonfinite constants are rejected at ingress.

Client configuration and provider compatibility covers Grok Build, xAI remote MCP, Codex, Gemini, VS Code, Cursor and Claude, distinguishing generated configuration from live-provider testing. Validator limits describe the conservative SQL/email/input contracts.

Installation

For most users, install MCPZT from PyPI into an isolated environment. This gives you the mcpzt command without cloning the repository.

python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade mcp-zero-trust-layer
mcpzt version

For one-off usage without keeping a permanent environment, use uvx or pipx run. This is a good fit when you want to initialize a config, validate a repository, generate client config or run a local wrapper from a clean install.

uvx mcp-zero-trust-layer version
pipx run mcp-zero-trust-layer version

For local development from this repository, create a virtual environment and install the package in editable mode.

python -m venv .venv
. .venv/bin/activate
python -m pip install -c constraints.txt -e ".[dev]"

The CLI exposes two command names. mcpzt is the short name for daily use, and mcp-zero-trust-layer is the full package-style name.

mcpzt version
mcp-zero-trust-layer version

Docker is also supported. Use the published GHCR image for release deployments, or build a local image when testing changes from a checkout. The Dockerfile installs the package with constraints.txt, which pins the configured dependency set while leaving PyPI dependency ranges flexible for library users. This is not a bit-for-bit reproducible-build guarantee.

docker run --rm ghcr.io/686f6c61/mcp-zero-trust-layer:0.6.0 version
docker build -t mcpzt:local .
docker run --rm mcpzt:local version

To refresh the moving image tag explicitly:

docker pull ghcr.io/686f6c61/mcp-zero-trust-layer:latest
docker run --rm ghcr.io/686f6c61/mcp-zero-trust-layer:latest version

The release workflow verifies public PyPI file hashes against the CI-approved artifacts and runs the v2 demo from both PyPI and the published GHCR image. The registry package page contains all image tags; latest moves with a stable release and is not an immutable reference.

You can validate an example config inside Docker without giving the container write access to the project.

docker run --rm \
  -v "$PWD/examples/multi-mcp:/cfg:ro" \
  mcpzt:local config validate --config /cfg/mcpzt.yaml

After any install path, run a small verification sequence. It proves that the CLI starts, config generation works, the schema validates and the client config generator can produce JSON without touching a real MCP server.

mcpzt init --config /tmp/mcpzt.yaml --force
mcpzt config validate --config /tmp/mcpzt.yaml
mcpzt config lint --config /tmp/mcpzt.yaml
mcpzt client config --config /tmp/mcpzt.yaml --kind json

If you want to see the gateway behave end to end before connecting a real MCP, generate the local demo. It creates a fake upstream MCP server, a policy file, a tiny client and a