governed-mcp

Governance that travels over the Model Context Protocol.

The governed co-workers — Understander, Calibrator, Navigator — exposed as an MCP server. Any MCP-capable client (Claude, or a platform built on Claude) mounts governance at the two points where it actually bites: the input and the handoff. Every decision leaves an owned, auditable evidence record as a byproduct — not by convention, but because the server can't act without writing one.

This is the thesis made literal: you don't attach governance to one system, you publish it and it travels to wherever it's mounted.

The interface

Tools (model-controlled actions)

• understand(action, context, principal) — reads intent, scope, sensitivity, and consequence class. Opens the evidence record under an owning principal.
• calibrate(decision_id, model_confidence) — is that confidence sufficient for this consequence? Not a flat threshold: the Calibrator tracks the outcomes of past decisions per consequence class and discounts stated confidence by an online reliability estimate before comparing it to the floor. A class whose confidence has proven only 80% trustworthy sees the same stated 0.85 fall to an effective 0.69. With no history reliability is 1.0, so it reduces exactly to a flat floor — a strict generalization, not a replacement. Every adjustment is returned in the record, so calibration is itself auditable. (This is a reliability-weighted estimator with shrinkage, not a trained calibrator; it depends on resolved outcomes fed via Calibrator.observe(), and that labeling is its own hard problem.)
• navigate(decision_id) — the handoff: proceed, gate, or block, plus the exact rule that fired.

Resources (read-only data)

• governance://policy — the versioned ruleset, as an auditable artifact.
• governance://evidence/{decision_id} — one decision's full record: inputs, every tool result, the route, timestamps, and the owning principal. This is the underwriter's read.

Prompt

• escalation_review(decision_id) — what the gate presents to the accountable human: the evidence, then "Would you sign your name to this outcome?"

Run the demo (no dependencies)

python examples/walkthrough.py

Act 1 — three decisions, three routes:

Action	Class	Confidence	Route
Read Q3 summary, draft internal note	reversible	0.88	proceed
Transfer $250k to external account	irreversible	0.99	gate
Bulk-modify customer PII records	bounded	0.79	block

Act 2 — calibration learns. The same action at the same stated confidence, judged differently as the agent builds a track record:

Pass	Reliability	Effective conf.	Floor	Route
cold start (no history)	1.00	0.85	0.80	proceed
after 40 overconfident outcomes	0.81	0.69	0.80	block

Nothing about the request changed — the system's earned trust in that confidence did, and the evidence record shows exactly why. That flip is the thing to screen-record.

Run the MCP server

pip install "mcp[cli]"
python -m governed_mcp.server        # stdio transport

To mount it in Claude Code / the desktop app, add it as an MCP server (stdio, command python -m governed_mcp.server). Then ask Claude to run an action through understand → calibrate → navigate and read back governance://evidence/{id}.

Design principle

Two things are enforced by the interface, not left to discipline:

1. Every tool call writes evidence. A decision cannot progress silently.
2. principal is required to open a decision. "Whoever deploys the agent owns the outcome" is captured mechanically — the record always answers who owns this.

Swapping in the real governed

The co-workers here are transparent stand-ins with the right interfaces. The real depth lives in your library's internals — the consequence classifier, the calibration thresholds, the policy engine. Replace the bodies of Understander.read, Calibrator.check, and Navigator.route in governed_mcp/coworkers.py; the server, resources, prompt, and evidence store stay as-is. The MCP layer is deliberately thin — the point it proves is that you know where governance attaches in an agentic system.

Tests

python tests/test_governance.py     # no pytest needed; pytest also works

Asserts the decisions a governance tool must get right: routes match consequence, sensitive scope raises the floor, every step writes evidence under a principal, and calibration flips a verdict as overconfidence accumulates.

Layout

governed-mcp/
├── governed_mcp/
│   ├── policy.py       # consequence bands, classification, calibration floors
│   ├── coworkers.py    # Understander, Calibrator (reliability-weighted), Navigator
│   ├── evidence.py     # EvidenceStore, Decision, owned records
│   └── server.py       # FastMCP: 3 tools, 2 resources, 1 prompt
├── policy.yaml         # editable ruleset (overrides default when pyyaml present)
├── examples/
│   └── walkthrough.py  # runnable, dependency-free demo (Act 1 + Act 2)
├── tests/
│   └── test_governance.py
├── requirements.txt
└── pyproject.toml