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.

┌────────────┐        ┌──────────────────────┐        ┌──────────────┐
│ 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)

---

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

pip install mcp-governance-proxy                # core
pip install "mcp-governance-proxy[wave]"        # + wave-engine evaluator integration

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

---

Quick start

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:

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, and everything is logged with a Wave score.

---

Try the demo locally

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

Server starts on http://localhost:9000. In another terminal:

# 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
curl http://localhost:9000/admin/holds

# Approve a held call
curl -X POST http://localhost:9000/admin/holds/<hold_id>/approve

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
/admin/holds/{id}/approve	POST	Approve a held call (executes it now)
/admin/holds/{id}/reject	POST	Reject a held call (drops it)

Python API

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:

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:

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.

---

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

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

---

License

Apache 2.0. See 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 — continuous 1–5 risk scoring (pairs with WaveEngineEvaluator)
• cross-system-correlator — pattern detection across multiple agent actions over time