# sovr-mcp-proxy
[](https://www.npmjs.com/package/sovr-mcp-proxy)
[](./LICENSE)
**Transparent MCP Proxy — The Execution Firewall for AI Agents.**
`sovr-mcp-proxy` is a superset of [`sovr-mcp-server`](https://www.npmjs.com/package/sovr-mcp-server). It includes all MCP Server capabilities **plus** a transparent proxy layer that intercepts, evaluates, and audits every agent→tool call against configurable policy rules before forwarding to downstream MCP servers.
## Architecture
```
┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ AI Agent │────▶│ sovr-mcp-proxy │────▶│ Downstream MCP │
│ (Claude etc) │ │ Gate-Check Layer│ │ (Stripe/GitHub) │
└─────────────┘ └──────────────────┘ └─────────────────┘
│
Policy Rules
Permit/Receipt
Audit Trail
```
## Key Differences: Proxy vs Server
| Feature | sovr-mcp-proxy | sovr-mcp-server |
|---------|---------------|-----------------|
| **286 Native Tools** | ✅ | ✅ |
| **1630 SDK Routes** | ✅ | ✅ |
| **Transparent Proxy Mode** | ✅ | ❌ |
| **Downstream Server Interception** | ✅ | ❌ |
| **Spawn/Discover/Intercept/Forward** | ✅ | ❌ |
| **Multi-server Routing** | ✅ | ❌ |
| **Anti-loop Protection** | ✅ | N/A |
| **Hop Counter** | ✅ | N/A |
## Quick Start
### Install
```bash
npm install -g sovr-mcp-proxy
```
### Claude Desktop Configuration
```json
{
"mcpServers": {
"sovr-proxy": {
"command": "npx",
"args": ["sovr-mcp-proxy"],
"env": {
"SOVR_API_KEY": "sovr_sk_...",
"SOVR_PROXY_CONFIG": "/path/to/proxy.json"
}
}
}
}
```
### Proxy Configuration (proxy.json)
```json
{
"downstream": {
"stripe": {
"command": "npx",
"args": ["@stripe/agent-toolkit"],
"env": { "STRIPE_SECRET_KEY": "sk_test_..." }
},
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "ghp_..." }
}
}
}
```
Every tool call to `stripe` or `github` is intercepted by SOVR's gate-check layer before forwarding.
## How It Works
1. **Spawn** — On startup, sovr-mcp-proxy spawns all downstream MCP servers as child processes
2. **Discover** — Enumerates tools from each downstream server via `tools/list`
3. **Intercept** — When the AI agent calls any tool, the proxy evaluates it against policy rules
4. **Gate-Check** — Applies permit/deny/escalate verdict based on rules
5. **Forward** — Approved calls are forwarded to the downstream server; denied calls return an error
## Security Features
### HTTPS Enforcement
All non-localhost connections are validated for HTTPS. HTTP connections to external hosts are rejected.
### Fail-Close / Fail-Local Degradation
- **Default (fail-close)**: If SOVR Cloud is unreachable, all gated operations are denied
- **Configurable (fail-local)**: Set `SOVR_FAIL_MODE=fail-local` to fall back to 20 built-in local rules
### Three-State Degradation
| Mode | Behavior | Use Case |
|------|----------|----------|
| `strict` (default) | Enforce all deny/escalate verdicts | Production |
| `record-only` | Log violations but allow execution | Emergency availability rescue |
| `propose-only` | Return verdict without executing | Dry-run / testing |
### Anti-Loop Protection
- Hop counter prevents infinite proxy chains (default max: 3 hops)
- Re-entry guard detects circular tool call patterns
### Data Redaction
Sensitive fields (`password`, `secret`, `token`, `key`, `authorization`, `cookie`, `ssn`, `credit_card`) are automatically redacted in all logs and audit entries.
### Unified Alert Dispatcher
Configurable alert routing to Webhook, Slack, PagerDuty, or OpsGenie (replaces hardcoded Telegram).
## Built-in Rules (Free Tier)
| Rule | Effect | Description |
|------|--------|-------------|
| Destructive Commands | **DENY** | Blocks `rm -rf`, `mkfs`, `dd`, `shred` |
| DDL Operations | **DENY** | Blocks `DROP`, `TRUNCATE`, `ALTER` |
| Privilege Escalation | **ESCALATE** | Flags `sudo`, `chmod`, `chown` for approval |
| Payment APIs | **ESCALATE** | Flags Stripe, PayPal calls for approval |
| Deployment Ops | **ESCALATE** | Flags deploy/publish/release for approval |
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SOVR_API_KEY` | No | Connect to SOVR Cloud for expanded tools and persistent audit |
| `SOVR_PROXY_CONFIG` | No | Path to proxy configuration JSON |
| `SOVR_RULES_FILE` | No | Path to custom rules JSON file |
| `SOVR_PROXY_MODE` | No | `strict` / `record-only` / `propose-only` (default: `strict`) |
| `SOVR_FAIL_MODE` | No | `fail-close` / `fail-local` (default: `fail-close`) |
| `SOVR_MAX_HOPS` | No | Max proxy hop count before loop detection (default: 3) |
| `SOVR_TENANT_ID` | No | Tenant identifier for multi-tenant deployments |
| `SOVR_ACTOR_ID` | No | Actor identifier for audit trail |
| `SOVR_SESSION_ID` | No | Session identifier for trace correlation |
| `SOVR_ENDPOINT` | No | Custom Cloud endpoint (advanced) |
## Tier Comparison
| | Free | Personal | Starter | Pro | Enterprise |
|---|---|---|---|---|---|
| **Tools** | 8 | 23 | 48 | 98 | 274 |
| **Built-in Rules** | 5 | 15+ | 15+ | 15+ | 15+ |
| **Custom Rules** | 3 | Unlimited | Unlimited | Unlimited | Unlimited |
| **Proxy Downstream** | 1 server | Unlimited | Unlimited | Unlimited | Unlimited |
| **Permit/Receipt** | Local only | Cloud | Cloud | Cloud | Cloud |
| **Audit Trail** | In-memory | Persistent | Persistent | Persistent | Persistent |
| **Approval Workflow** | — | Basic | Full | Full | Full + SLA |
Free tier works offline with zero configuration. Upgrade at [sovr.inc/pricing](https://sovr.inc/pricing).
## Related Packages
- [`sovr-mcp-server`](https://www.npmjs.com/package/sovr-mcp-server) — MCP Server mode only (no proxy capabilities)
## License
[BSL-1.1](./LICENSE) — Code is source-available. Free for non-commercial use. Commercial use requires a license from SOVR AI.
After the Change Date (February 18, 2030), this software converts to Apache-2.0.
---
**SOVR — Eyes on AI.** [sovr.inc](https://sovr.inc)
