flowchart LR
    subgraph clients["fa:fa-user MCP clients"]
        direction TB
        C1["fa:fa-desktop Desktop assistant<br/>stdio"]
        C2["fa:fa-robot Agent runtime<br/>Streamable HTTP"]
    end

    subgraph idp["fa:fa-id-badge Identity provider"]
        J["JWKS"]
    end

    subgraph gw["fa:fa-shield-halved Gateway, one pipeline for every tool"]
        direction TB
        G1["Authenticate"] --> G2["Rate limit"] --> G3["Authorise by role"] --> G4["Confirm writes"]
        G5["Redact"] --> G6["Audit"]
    end

    subgraph srv["fa:fa-server MCP servers"]
        direction TB
        S1["cloud-inventory"]
        S2["runbooks"]
        S3["tickets"]
    end

    subgraph be["fa:fa-database Systems behind them"]
        direction TB
        B1["Resource inventory and cost"]
        B2["Runbook library"]
        B3["Ticketing"]
    end

    C1 --> G1
    C2 --> G1
    J -. verify token .-> G1
    G4 --> S1 & S2 & S3
    S1 --> B1
    S2 --> B2
    S3 --> B3
    S1 & S2 & S3 -. result .-> G5
    G6 --> L["fa:fa-file-lines audit.jsonl"]

    classDef client fill:#0b1f4d,stroke:#7fa6ff,stroke-width:2px,color:#ffffff
    classDef gate fill:#2456c8,stroke:#c9d8ff,stroke-width:2px,color:#ffffff
    classDef server fill:#1a3a8a,stroke:#7fa6ff,stroke-width:2px,color:#ffffff
    classDef backend fill:#16367f,stroke:#7fa6ff,stroke-width:2px,color:#ffffff
    classDef ext fill:#ffffff,stroke:#2456c8,stroke-width:2px,color:#0b1f4d
    class C1,C2 client
    class G1,G2,G3,G4,G5,G6 gate
    class S1,S2,S3 server
    class B1,B2,B3 backend
    class J,L ext

sequenceDiagram
    autonumber
    participant U as User
    participant A as AI assistant
    participant G as Gateway
    participant T as tickets server
    participant L as Audit log
    U->>A: Open a ticket for the queue backlog
    A->>G: create_ticket(title, service)
    G->>L: deny, needs confirm=true
    G-->>A: Denied. Show the user and ask first
    A->>U: I will open "Queue backlog on batch" as sev3. Go ahead?
    U->>A: Yes
    A->>G: create_ticket(title, service, confirm=true)
    G->>G: token valid, role operator, under rate limit
    G->>T: create
    T-->>G: TCK-1007, reporter lee@example.test
    G->>G: redact PII
    G->>L: allow, ok, 1 redaction
    G-->>A: TCK-1007, reporter [REDACTED:email]

git clone https://github.com/marlyngiselle/governed-mcp-gateway.git
cd governed-mcp-gateway
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest

governed-mcp dev-keys --out .dev
export GOVERNED_MCP_ISSUER=https://idp.example.test GOVERNED_MCP_AUDIENCE=governed-mcp
export GOVERNED_MCP_JWKS_FILE=.dev/jwks.json GOVERNED_MCP_PORT=8003 GOVERNED_MCP_AUDIT_LOG=.dev/audit.jsonl
governed-mcp serve tickets --transport http &

export GOVERNED_MCP_TOKEN=$(governed-mcp dev-token --role operator)
python examples/call_tool.py http://127.0.0.1:8003/mcp search_tickets '{"status": "open", "limit": 2}'

export GOVERNED_MCP_TOKEN=$(governed-mcp dev-token --role reader)
python examples/call_tool.py http://127.0.0.1:8003/mcp create_ticket '{"title": "Smoke test", "description": "Created from the quick start.", "service": "platform", "confirm": true}'

# policies/reader.yaml
role: reader
description: Read-only access for assistants that answer operational questions.
priority: 10
allow_writes: false
tools:
  allow:
    - "cloud-inventory.*"
    - "runbooks.*"
    - "tickets.search_tickets"
    - "tickets.get_ticket"
  deny:
    - "cloud-inventory.cost_by_tag"
rate_limit:
  requests_per_minute: 30
  burst: 10

{"ts":"2026-10-26T14:41:08.590+00:00","event":"tool_call","request_id":"623586b5-857b-4484-b915-b70beddda200","server":"tickets","tool":"create_ticket","access":"write","principal":"lee@example.test","client_id":"local-mcp-client","role":"operator","auth":"oidc","args_hash":"5f236d71e5166adebacbb137a44f70587f5b8c002a6d9513880f9b181ef7413a","args_hash_alg":"sha256","decision":"deny","reason":"'tickets.create_ticket' changes state and needs confirm=true. Show the user what will be done and ask before retrying.","outcome":"denied","latency_ms":0.051,"redactions":0}