Content
# 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)
```bash
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
```bash
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
```bash
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
```
