mcp-proxy

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

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

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

🗺️ Roadmap

• SSE transport support
• OPA policy engine
• SQLite audit logging
• 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.