Skip to main content
Glama
mcp-policy-gateway

mcp-policy-gateway

by jcorrego

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

get_case(case_id)

Read

Allows only cases in the caller's tenant with the right scope.

get_account_summary(account_id)

Read

Returns a minimized summary; never direct PII.

request_account_freeze(...)

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.

get_freeze_request(request_id)

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_ID

The 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.demo

The demo generates a temporary RSA keypair, an agent token and a separate approver token. It starts a real MCP stdio subprocess and runs:

  1. an allowed read and a cross-tenant denial;

  2. an approval-required freeze request, followed by a replay that returns the same request;

  3. the agent trying to approve its own request through the operator CLI, which is denied;

  4. a human approval and execution in separate operator processes;

  5. 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-gateway

The 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:

  1. denies an agent from tenant_red trying to read tenant_blue data;

  2. denies a tool call without its required scope;

  3. does not return owner name or email through the summary tool;

  4. returns require_approval rather than mutating account state; and

  5. rejects state-changing requests that omit a reason or idempotency key;

  6. refuses self-approval, approval without the approver scope, and cross-tenant approval;

  7. returns the same request for an idempotent replay and denies key reuse with a different payload;

  8. refuses illegal transitions, approval after expiry and execution before approval;

  9. produces exactly one approval decision when six approvers race;

  10. resumes from executing after a timeout that follows upstream execution, with one effect and a complete correlated audit trail; and

  11. aborts any UPDATE or DELETE on 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 tools
get_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

    A3.5/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enforces 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables governing tenant-aware MCP tools with policy enforcement, scoped access, human approval workflows, and tamper-evident audit logging.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enforces default-deny policies, budgets, and tamper-evident audit logging for MCP tool calls before they reach upstream servers.
      -