Why MCP Proxy?

As AI agents gain access to more powerful tools, security becomes critical. MCP Proxy sits between your AI agents and MCP servers, providing:

✨ Features

| Feature | Description | |---------|-------------| | OPA Policy Engine | Write policies in Rego for fine-grained access control | | SQLite Audit Store | Persistent, queryable audit logs with configurable retention | | SSE Transport | Server-Sent Events for real-time bidirectional communication | | Session Management | Secure session handling with TTL and connection limits | | Prometheus Metrics | Request latency, policy decisions, error rates | | Health Checks | Kubernetes-ready liveness and readiness probes | | TLS Support | Encrypted communications for production deployments |

🚀 Quick Start

Option 1: Go Install

go install github.com/agentfacts/mcp-proxy/cmd/proxy@latest

Option 2: Build from Source

git clone https://github.com/agentfacts/mcp-proxy.git
cd mcp-proxy
make build
./bin/mcp-proxy --config config/proxy.yaml

Option 3: Docker

docker run -p 3000:3000 ghcr.io/agentfacts/mcp-proxy:latest

# Start PostgreSQL, Redis, and supporting services
make docker-up

# Or with the full stack including the proxy
docker-compose --profile full up -d

⚙️ Configuration

Create a config.yaml file:

version: "1.0"

server:
  listen:
    address: "0.0.0.0"
    port: 3000
  transport: "sse"

upstream:
  url: "http://your-mcp-server:8080"
  transport: "sse"

policy:
  enabled: true
  mode: "enforce"      # "audit" to log only, "enforce" to block
  policy_dir: "policies"

audit:
  enabled: true
  db_path: "audit.db"

📜 Writing Policies

Policies are written in Rego, OPA's declarative policy language.

Example: Restrict File System Access

package mcp.policy

default allow = false

# Allow read operations for agents with read capability
allow {
    input.method == "tools/call"
    startswith(input.tool, "read_")
    has_capability("read:*")
}

# Block write operations to sensitive directories
deny {
    input.method == "tools/call"
    input.tool == "write_file"
    startswith(input.arguments.path, "/etc/")
}

# Helper: check if agent has capability
has_capability(cap) {
    input.agent.capabilities[_] == cap
}

Example: Rate Limiting

package mcp.policy

# Limit to 100 requests per session
deny {
    input.session.request_count > 100
}

See policies/ for more examples.

📈 Performance

MCP Proxy is designed for minimal overhead:

| Operation | Latency | Allocations | |-----------|---------|-------------| | Route Message | ~1 µs | 26 allocs | | Parse Request | ~337 ns | 5 allocs | | Generate Request ID | ~87 ns | 1 alloc |

go test -bench=. -benchmem ./internal/router/...

📊 Observability

Metrics (Prometheus)

Enable with metrics.enabled: true:

curl http://localhost:9090/metrics

Available metrics:

• mcp_proxy_requests_total - Total requests by method and status
• mcp_proxy_request_duration_seconds - Request latency histogram
• mcp_proxy_policy_decisions_total - Policy decisions by result
• mcp_proxy_active_sessions - Current active sessions

Health Checks

Enable with health.enabled: true:

# Liveness probe
curl http://localhost:8080/health

# Readiness probe
curl http://localhost:8080/ready

🗂️ Project Structure

mcp-proxy/
├── cmd/proxy/           # Application entry point
├── config/              # Configuration files
├── docs/                # Documentation
├── internal/
│   ├── audit/           # SQLite audit store
│   ├── config/          # Configuration loading
│   ├── observability/   # Metrics & health checks
│   ├── policy/          # OPA policy engine
│   ├── router/          # Message routing
│   ├── session/         # Session management
│   ├── transport/sse/   # SSE transport
│   └── upstream/        # Upstream client
├── policies/            # Example Rego policies
└── scripts/             # Utility scripts

📚 Documentation

| Document | Description | |----------|-------------| | Setup Guide | Detailed installation and configuration | | Contributing | How to contribute | | Changelog | Version history | | Security | Security policy |

🗺️ Roadmap

• [x] SSE transport support
• [x] OPA policy engine
• [x] SQLite audit logging
• [x] Prometheus metrics
• [ ] STDIO transport
• [ ] HTTP transport
• [ ] WebSocket transport
• [ ] AgentFacts verification
• [ ] Policy hot-reload
• [ ] Admin API
• [ ] Web dashboard

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

# Clone the repo
git clone https://github.com/agentfacts/mcp-proxy.git
cd mcp-proxy

# Install dependencies
go mod download

# Run tests
make test

# Run linter
make lint

📄 License

MIT License - see LICENSE for details.