# mcp-governance-proxy

**An MCP server that sits between AI agents and the systems they act on. Evaluates every tool call before it executes. Holds risky ones for human review.**

Built for teams running AI agents (Claude Desktop, Cursor, Cline, in-house) that need to govern what those agents can actually do on real systems — without rewriting every agent to add policy checks.

```text
┌────────────┐        ┌──────────────────────┐        ┌──────────────┐
│ MCP Client │        │ mcp-governance-proxy │        │ Real Systems │
│ (Claude    │  MCP   │                      │  API   │ Slack        │
│  Desktop,  │ ─────► │  1. evaluate         │ ─────► │ GitHub       │
│  Cursor,   │        │  2. auto/hold/block  │        │ AWS          │
│  Cline)    │        │  3. log every action │        │ ...          │
└────────────┘        └──────────────────────┘        └──────────────┘
                              ▲
                              │ credentials live here
                              │ (never in the agent)
```

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

---

## Why this exists

Today's AI agents call tools — Slack, GitHub, Stripe, internal APIs. Two real problems:

1. **The agent holds the credentials.** If the agent is compromised, or the model is jailbroken, or it just makes a mistake, the credentials are weaponized. Most production agent setups treat OAuth tokens as if they're throwaway.

2. **There's no consistent place to evaluate "should this happen?"** Policy lives scattered in agent code, infra rules, vendor-specific consoles, or nowhere at all. Adding governance means rewriting every agent.

This proxy solves both. The agent talks MCP to the proxy. The proxy holds the credentials, evaluates every call through a pluggable policy engine, executes if allowed, holds for review if risky, blocks if disallowed. The agent never sees a real API token.

---

## Install

This project is not published on PyPI yet. Install straight from GitHub:

```bash
pip install "git+https://github.com/andreas-altamirano/mcp-governance-proxy"                  # core
pip install "mcp-governance-proxy[wave] @ git+https://github.com/andreas-altamirano/mcp-governance-proxy"   # + wave-engine evaluator
```

Python 3.9+. Depends on `fastapi`, `httpx`, `pydantic`, `uvicorn`.

> **Security note — read before running this for real:** the `/admin` endpoints approve held calls, so they require a secret token (`MCP_PROXY_ADMIN_TOKEN`). See [Security](#security).

---

## Quick start

```python
from mcp_governance_proxy import GovernanceProxy, AllowListEvaluator, create_app
from mcp_governance_proxy.adapters import SlackAdapter, GitHubAdapter

# 1. Build the proxy: evaluator + adapters
proxy = GovernanceProxy(
    evaluator=AllowListEvaluator(allowed_tools=[
        "slack_send_message",
        "github_create_issue",
    ]),
    adapters=[
        SlackAdapter(),    # reads SLACK_BOT_TOKEN from env
        GitHubAdapter(),   # reads GITHUB_TOKEN from env
    ],
)

# 2. Wrap in a FastAPI app
app = create_app(proxy)

# 3. Run
#    uvicorn yourmodule:app --port 9000
```

Point any MCP client at `http://localhost:9000/mcp` and it can now use `slack_send_message` and `github_create_issue` — but only those, and only after the proxy evaluates each call.

---

## Plug in wave-engine for nuanced policy

`AllowListEvaluator` is binary. For continuous 1–5 risk scoring (auto-execute the safe, hold the risky for review, block the worst), pair the proxy with [wave-engine](https://github.com/andreas-altamirano/wave-engine):

```python
from wave_engine import (
    Rule, Wave, WaveEvaluator,
    match_all, match_action, match_context_gt, match_system,
)
from mcp_governance_proxy import GovernanceProxy, WaveEngineEvaluator, create_app
from mcp_governance_proxy.adapters import SlackAdapter

policy = WaveEvaluator(rules=[
    Rule(
        name="high_value_refund",
        matcher=match_all(
            match_system("stripe"),
            match_action("refund"),
            match_context_gt("amount", 100),
        ),
        score=30,
        min_wave=Wave.REVIEW,   # force hold-for-human
        reason="Refund over $100",
    ),
])

proxy = GovernanceProxy(
    evaluator=WaveEngineEvaluator(policy),
    adapters=[SlackAdapter()],
)
app = create_app(proxy)
```

Now refunds under $100 auto-execute, refunds over $100 hold for human approval at `/admin/holds` (token required, see [Security](#security)), and everything is logged with a Wave score.

---

## Try the demo locally

```bash
git clone https://github.com/andreas-altamirano/mcp-governance-proxy
cd mcp-governance-proxy
pip install -e ".[dev]"
MCP_PROXY_ADMIN_TOKEN=demo-token python examples/minimal_server.py
```

Server starts on `http://localhost:9000` (localhost only). In another terminal:

```bash
# List available tools
curl -X POST http://localhost:9000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Tool call that auto-executes
curl -X POST http://localhost:9000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"demo_send_message",
                 "arguments":{"channel":"#general","text":"hi"}}}'

# Tool call that gets held for review
curl -X POST http://localhost:9000/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"demo_refund","arguments":{"amount":500}}}'

# See what's pending review (needs the admin token)
curl http://localhost:9000/admin/holds \
  -H 'Authorization: Bearer demo-token'

# Approve a held call
curl -X POST http://localhost:9000/admin/holds/<hold_id>/approve \
  -H 'Authorization: Bearer demo-token'
```

The demo runs without any real API tokens — it uses a fake adapter that just echoes what it received.

---

## API surface

### HTTP endpoints (from `create_app`)

| Endpoint | Method | Purpose |
|---|---|---|
| `/mcp` | POST | MCP JSON-RPC: `initialize`, `tools/list`, `tools/call` |
| `/health` | GET | Liveness check |
| `/admin/holds` | GET | List held calls awaiting review. **Bearer token required.** |
| `/admin/holds/{id}/approve` | POST | Approve a held call (executes it now). **Bearer token required.** |
| `/admin/holds/{id}/reject` | POST | Reject a held call (drops it). **Bearer token required.** |

The admin endpoints return `401` for a missing or wrong token, and `503` if no admin token is configured at all (they are disabled by default, never left open).

### Python API

```python
GovernanceProxy(evaluator, adapters, hold_queue=InMemoryHoldQueue())

# Async entry point
await proxy.handle_call(ToolCall(tool, arguments, client_id=None)) -> CallOutcome

# Review surface
await proxy.approve_held(hold_id) -> CallOutcome
proxy.reject_held(hold_id) -> bool
proxy.hold_queue.list_pending() -> list[HeldCall]
```

---

## Plug in your own evaluator

Implement the `Evaluator` protocol:

```python
from mcp_governance_proxy import EvaluationResult, ToolCall

class MyEvaluator:
    async def evaluate(self, call: ToolCall) -> EvaluationResult:
        if call.tool == "send_money" and call.arguments.get("amount", 0) > 10000:
            return EvaluationResult(allow=False, hold=True,
                                    reason="Large transfer needs review")
        return EvaluationResult(allow=True, reason="OK")

proxy = GovernanceProxy(evaluator=MyEvaluator(), adapters=[...])
```

That's the whole interface. Evaluators can call out to OPA, query an external policy service, run an LLM classifier, or anything else — the proxy doesn't care.

---

## Plug in your own tool adapter

Implement the `ToolAdapter` protocol:

```python
class JiraAdapter:
    @property
    def tool_names(self):
        return ["jira_create_ticket"]

    @property
    def tool_schemas(self):
        return {
            "jira_create_ticket": {
                "type": "object",
                "description": "Create a Jira ticket.",
                "properties": {
                    "project": {"type": "string"},
                    "summary": {"type": "string"},
                    "description": {"type": "string"},
                },
                "required": ["project", "summary"],
            }
        }

    async def execute(self, call):
        # call your Jira API, return the result
        ...
```

Reference adapters live in `mcp_governance_proxy/adapters.py` — `SlackAdapter`, `GitHubAdapter`, and a generic `WebhookAdapter`. Copy and adapt for your systems.

---

## Security

This is an early prototype. Know what it does and doesn't protect.

**Admin token.** Approving a held call executes it, so the `/admin` endpoints require `Authorization: Bearer <token>`. Set the token with the `MCP_PROXY_ADMIN_TOKEN` environment variable or `create_app(proxy, admin_token=...)`. With no token set, the admin API is disabled (HTTP 503). **Never give this token to the agent** — anything that holds it can approve its own held calls. Keep it out of the agent's environment, config, and tool access.

**Keep the proxy off the open internet.** Bind to localhost or a private network, and put TLS and network controls in front of it. The demo binds to `127.0.0.1` for this reason.

**The agent must have no other route to your credentials.** The proxy only helps if every action goes through it. If the agent also has the raw Slack or GitHub token somewhere, the proxy can be bypassed.

**`client_id` is not an identity.** The proxy reads it from a request header the client controls, so it can be spoofed. Don't write policy that trusts it as proof of who is calling.

**Input validation.** The GitHub adapter only accepts `repo` in strict `owner/name` form and `issue_number` as a positive integer. If you write your own adapter, validate everything the agent sends before it touches a URL, command, or query.

**Known limitations (not fixed yet):**
- Held calls live in memory and are lost on restart.
- There is no record of who approved a held call, and the policy is not re-checked at approval time.
- No rate limiting. Logging goes through Python's standard logging only; there is no durable audit store.

Found a security problem? Please open an issue or contact the maintainer.

---

## What this is *not*

- **Not a policy authoring tool.** Write policy in `wave-engine`, OPA, Cedar, plain Python, or whatever else. This is the runtime that enforces it.
- **Not a full MCP SDK.** It speaks enough of MCP JSON-RPC for Claude Desktop and similar clients. For full streamable-transport / stdio MCP support, swap the HTTP layer for the official [mcp-python](https://github.com/modelcontextprotocol/python-sdk) SDK.
- **Not a credential vault.** Credentials live in env vars or whatever your existing secret store provides. The proxy reads them when it needs them.
- **Not a UI.** The `/admin/holds` endpoint returns JSON. Build whatever review UI fits your team on top of it.

---

## Tests

```bash
pip install -e ".[dev]"
pytest -q
```

---

## License

Apache 2.0. See [LICENSE](LICENSE).

---

## Acknowledgments

Extracted and generalized from the MCP governance layer of **Surfit**, an AI agent governance platform. Released so other teams can build governance into their agent stacks without committing to a full platform.

Companion libraries:

- [`wave-engine`](https://github.com/andreas-altamirano/wave-engine) — continuous 1–5 risk scoring (pairs with `WaveEngineEvaluator`)
- [`cross-system-correlator`](https://github.com/andreas-altamirano/cross-system-correlator) — pattern detection across multiple agent actions over time