mcp-policy-gateway
Summary: This MCP server provides tenant-scoped read tools plus a human-approval-gated account freeze request, with no MCP approval or execution tool.
Retrieve support cases only inside the caller's tenant boundary (and with the right scope).
Read minimized account summaries that do not expose direct PII.
Request a high-impact account freeze with a reason and idempotency key; the request becomes pending human approval and does not mutate account state.
Approval and execution are operator-only outside MCP, so the agent cannot self-approve or directly execute freezes.
The schema exposes exactly these three tools; it does not expose
get_freeze_requesteven though the README mentions it.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-policy-gateway Get the account summary for account 9876543210"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-policy-gateway
A policy-first MCP server reference implementation. It shows how to give an agent useful tools without allowing the model to decide authorization, cross tenant boundaries, leak direct PII, or execute high-impact mutations on its own.
This is a portfolio/reference implementation. Every record is synthetic; it is not production software and does not claim to integrate with a bank, payment processor, or customer system.
Why this exists
A common MCP demo exposes a raw API to a model and treats a successful tool call as a security model. This project takes the opposite position:
Policy is deterministic. The model cannot authorize itself.
Tenant boundary is enforced server-side. A tool argument cannot switch tenant.
Tool output is minimized. The account summary intentionally excludes owner name and email.
High-impact actions stop at an approval gate. A freeze request is stored as a pending approval and changes no account state. Only a different, human approver identity can approve it, and only through the operator CLI. MCP has no approve tool.
Approved actions execute once. A store-enforced state machine, idempotent replays and an idempotent upstream token mean that a timeout after execution resumes the request without freezing the account twice.
Every decision is auditable. Allow, deny, approval and execution outcomes go to an append-only audit table, with a correlation ID per request.
Mutation requests require a reason and idempotency key.
Related MCP server: Aegis
Architecture
MCP client / agent
│ tool call
▼
FastMCP stdio adapter
│ JWT verified with operator-pinned public key (at startup and per call)
▼
GatewayService ──► PolicyEngine ──► allow / deny / require approval
│ │
▼ ▼
synthetic domain data ApprovalStore (SQLite): approval requests + append-only audit
▲
human approver ──► operator CLI ─┘ approve / reject / execute ──► synthetic upstream
(own verified JWT, approver scope, never the requester) (idempotent on request ID)The launcher supplies a JWT, issuer, audience and pinned public key through its environment. The adapter derives the principal from the verified session, outside model-controlled arguments. The bundled test issuer exists only for synthetic tests and the demo; it is not an OIDC provider. The policy engine loads a versioned configuration snapshot at startup. See ADR 001, ADR 002 and ADR 003.
Tools
Tool | Risk | Behaviour |
| Read | Allows only cases in the caller's tenant with the right scope. |
| Read | Returns a minimized summary; never direct PII. |
| Mutation | Requires a scope, reason and idempotency key, then stores a pending request that always requires human approval. A retry with the same key returns the same request. |
| Read | Returns a request's state inside the caller's tenant. |
Operator-only commands, deliberately not exposed over MCP:
mcp-policy-gateway-approvals approve REQUEST_ID --note "why"
mcp-policy-gateway-approvals reject REQUEST_ID --note "why"
mcp-policy-gateway-approvals execute REQUEST_ID
mcp-policy-gateway-approvals audit REQUEST_IDThe CLI reads the approver's own token from the same GATEWAY_* launch variables and requires GATEWAY_STATE_DB. Request states are requested → approved | rejected | expired and approved → executing → executed; any other transition is refused.
Quickstart
Requires Python 3.11+.
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/python -m mcp_policy_gateway.demoThe demo generates a temporary RSA keypair, an agent token and a separate approver token. It starts a real MCP stdio subprocess and runs:
an allowed read and a cross-tenant denial;
an approval-required freeze request, followed by a replay that returns the same request;
the agent trying to approve its own request through the operator CLI, which is denied;
a human approval and execution in separate operator processes;
the agent reading back the executed request and the now-frozen account, plus the correlated audit trail. Run as an MCP stdio server with your trusted launcher:
.venv/bin/mcp-policy-gatewayThe launcher must set GATEWAY_ID_TOKEN, GATEWAY_JWT_PUBLIC_KEY_FILE, GATEWAY_ISSUER and GATEWAY_AUDIENCE. The key file contains only the issuer's public key. The JWT must be signed with RS256 and contain iss, aud, sub, tenant_id, a space-delimited scope, iat and exp. Missing or invalid settings fail startup. Never pass the token as a tool argument or commit it to this repository. These launch variables are for a one-identity stdio process, not multi-tenant remote transport. Set GATEWAY_STATE_DB to a SQLite file path to keep approval requests and audit events across restarts and share them with the operator CLI. Without it, the server keeps them in memory.
The installed package uses policy-v2.json by default. To deploy a reviewed policy file, set GATEWAY_POLICY_FILE to its absolute path in the trusted launcher. Each rule specifies scope and risk, and every exposed tool needs a rule. request_account_freeze must keep mutation risk and also declare an approver_scope and an approval_ttl_seconds value between 60 and 86400. The approver scope may not equal any tool scope. Invalid configurations abort startup. Tool results and audit events include policy_version; denials include a machine-readable reason. A running server keeps its startup snapshot, so restart it to apply a new file. The version is an operator-provided label, not cryptographic proof of policy contents.
Demonstrated abuse controls
The tests prove the gateway:
denies an agent from
tenant_redtrying to readtenant_bluedata;denies a tool call without its required scope;
does not return owner name or email through the summary tool;
returns
require_approvalrather than mutating account state; andrejects state-changing requests that omit a reason or idempotency key;
refuses self-approval, approval without the approver scope, and cross-tenant approval;
returns the same request for an idempotent replay and denies key reuse with a different payload;
refuses illegal transitions, approval after expiry and execution before approval;
produces exactly one approval decision when six approvers race;
resumes from
executingafter a timeout that follows upstream execution, with one effect and a complete correlated audit trail; andaborts any
UPDATEorDELETEon the audit table.
The identity tests also exercise expired/wrong-audience tokens, bad signatures, malformed claims, untrusted tenant/scope arguments and a real MCP client/server exchange.
Threat model and non-goals
See THREAT_MODEL.md. This is a pinned-key JWT verification seam, not full OIDC discovery, key rotation, revocation, secrets management or a payment/ledger system. Approval state uses SQLite, not PostgreSQL. The audit triggers block application-level edits but are not tamper-evident against someone who can write to the database file. The upstream is a synthetic table.
Interview walkthrough
A concise way to explain the project:
I designed the MCP boundary so the model can reason over safe, scoped data but cannot decide access or execute high-impact actions. Authorization is deterministic, tenant isolation is enforced server-side, and the tool surface minimizes PII. A sensitive mutation becomes a durable request that only a different human identity can approve, outside MCP. Execution is idempotent end to end, so a timeout after the upstream call resumes the request instead of applying it twice.
Development
.venv/bin/pytest
.venv/bin/ruff check .CI runs lint, tests and the demo on pushes and pull requests, and uploads the demo output as an artifact. A second job installs the declared dependency floors (mcp==1.22.0, pyjwt==2.10.1) and runs the suite again. Older mcp releases fail to import against current pydantic.
License
MIT. See LICENSE.
Available Tools
3 toolsget_account_summaryB
Return a minimized account summary; this tool never exposes direct PII.
Inputs: account_id (required).
get_caseA
Retrieve a support case inside the caller's tenant boundary.
Inputs: case_id (required).
request_account_freezeB
Request a high-impact account freeze. Policy always requires human approval.
Inputs: reason (required), account_id (required), idempotency_key (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct resource/action: case retrieval, account summary (with PII restriction), and a freeze request. There is no overlap in purpose, and the descriptions clearly differentiate the operations.
All tool names follow a consistent verb_noun pattern (get_case, get_account_summary, request_account_freeze). The verbs are clear and the nouns identify the target, making the set predictable and easy to navigate.
With only 3 tools, the server is tightly scoped and each tool serves a distinct, essential function within the policy gateway context. This is within the typical 3-15 range and feels appropriately lean rather than sparse.
The tools cover core read operations and a high-impact action, but there are notable gaps: no listing of cases or accounts, no update/modification paths, and no way to track the status of a freeze request. Agents would need to work around these missing operations.
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
One MCP endpoint for your company's tools, with per-person sign-in, policy and audit.
Governed MCP gateway for business apps: roles, previews, approvals and one audit log.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnforces fine-grained, context-aware access control on MCP tool calls, with a tamper-evident, replayable audit log that records denials and verifies every decision.MIT
- AlicenseNot gradedqualityDmaintenanceEnables governing tenant-aware MCP tools with policy enforcement, scoped access, human approval workflows, and tamper-evident audit logging.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and MCP clients to safely access upstream MCP servers through centralized policy enforcement, including allow/deny/approval decisions, schema pinning, circuit breakers, and audit logging.MIT
- FlicenseNot gradedqualityCmaintenanceEnforces default-deny policies, budgets, and tamper-evident audit logging for MCP tool calls before they reach upstream servers.-