MCP Control Plane

A hardened gateway that sits between AI agents (LLM clients) and real infrastructure APIs (Kubernetes, Terraform, Jenkins, Prometheus, ticketing). Every tool call is authenticated, rate-limited, policy-checked via OPA, and audited before it reaches an executor. The model is treated as an untrusted caller — the policy engine, not the prompt, is the actual security boundary.

Full target architecture, threat model, and API design live in docs/; this README covers what's implemented today and how to run it.

Status

Actively under development, tracked in docs/roadmap.md. Currently implemented:

• MCP JSON-RPC gateway (tools/list, tools/call) over HTTP, plus an SSE heartbeat endpoint
• API key authentication, resolving each key to an agent identity (id, role, allowed_tools)
• Redis-backed sliding-window rate limiting, per agent
• Tool call interception, normalization, and an OPA policy check (allow / deny / require_approval)
• 11 tool executors — currently stubs, real downstream API calls land per docs/roadmap.md Phase 3
• Structured audit logging to stdout (durable, hash-chained Postgres storage is a later phase)

Not yet built: real tool executors, the human-in-the-loop approval workflow, persistent audit storage, and observability (OTel/Grafana) — see the roadmap for sequencing.

Architecture

Agent → POST /mcp → [log] → [authn] → [rate limit] → interceptor → OPA → executor → audit log

• app/main.py — FastAPI app, route handlers, middleware wiring
• app/middleware/auth.py — API key → agent identity
• app/middleware/rate_limit.py — Redis sliding-window limiter
• app/interceptor.py — validates/normalizes tools/call params into an OPA input document
• app/authz/opa.py — calls the OPA sidecar, maps its response to allow/deny/require_approval
• app/tools/tools_spec.py — tool executors (stubs today)
• app/audit.py — audit trail of every tool call
• policies/ — Rego policy (authz.rego) and role/tool data (data.json) loaded by OPA

See docs/architecture.md for the full target-state design (EKS, Terraform, Postgres audit log, approval gate, observability stack).

Tech stack

Python 3.13, FastAPI, Redis, OPA/Rego, Docker Compose. See pyproject.toml for exact dependency versions.

Getting started

Prerequisites

• Python 3.13+ and uv
• Docker (for Redis/Postgres/OPA via Compose), or your own local instances

Install

uv sync

Run

Everything (gateway + Redis + Postgres + OPA) via Docker Compose:

docker compose up

Or the gateway alone against local dependencies:

uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

The app reads REDIS_URL (default redis://localhost:6379) and OPA_URL (default http://localhost:8181/v1/data/authz) from the environment; Compose sets both to point at the sibling containers.

Try it

All /mcp routes require an x-api-key header. The seeded dev key test_key resolves to agent01 (role sre1) with a handful of allowed tools — see API_KEYS in app/middleware/auth.py.

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" -H "x-api-key: test_key" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" -H "x-api-key: test_key" \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/call","params":{"name":"get_pod_logs","arguments":{"namespace":"payments","pod_name":"checkout-api-xyz"}}}'

curl -s http://127.0.0.1:8000/health/live

More request/response examples (error cases, SSE) are in testing/testing.text.

Testing

uv run pytest

Covers the auth middleware, rate limiter, OPA integration, and end-to-end /mcp request handling (see tests/).

Documentation

Doc	Contents
docs/roadmap.md	Phased build plan and current progress
docs/architecture.md	Full target-state system design
docs/api-design.md	MCP + admin API surface
docs/tool-spec.md	Per-tool input/output schemas and policy constraints
docs/threat-model.md	STRIDE threat model and mitigations