Arbitus

Open-source firewall for MCP tool calls. Arbitus sits between AI agents and MCP servers, then blocks secret leaks, dangerous tools, runaway loops, and unapproved actions before requests reach upstream.

Agent (Claude Code, Cursor, OpenAI Agents SDK, etc.)
        │  JSON-RPC
        ▼
      arbitus     ← auth, rate limit, HITL, payload filter, audit
        │
        ▼
  MCP Server (filesystem, database, APIs...)

Use it when you want developers to keep using AI agents without giving every agent unrestricted access to your filesystem, databases, internal APIs, or production tools.

Why teams use it

• Stop secret exfiltration — block or redact .env values, API keys, private keys, bearer tokens, and encoded variants before they leave the agent runtime
• Constrain agent tools — expose only approved tools through tools/list, then enforce the same policy on tools/call
• Control blast radius — rate-limit agents per minute, per tool, and per IP so loops do not become budget or infrastructure incidents
• Approve risky actions — require Human-in-the-Loop approval before writes, deletes, deploys, database mutations, or shell-like tools run
• Keep an audit trail — record every decision with request IDs and send events to SQLite, webhooks, CloudEvents, OpenLineage, Prometheus, or OTLP backends

Threats Arbitus blocks

What it does

• Auth — per-agent allowlist/denylist with glob wildcards; API key, JWT/OIDC, or mTLS
• tools/list filtering — agents only see the tools they are allowed to call
• Resource & Prompt access control — allowed_resources/denied_resources and allowed_prompts/denied_prompts with list filtering; full MCP protocol governance
• Default policy — fallback policy for unknown agents; avoids hard-blocking agents not listed in config
• Rate limiting — per-agent sliding window + per-tool limits + per-IP limit; standard X-RateLimit-* headers
• Human-in-the-Loop (HITL) — suspend tool calls until an operator approves or rejects via REST API
• Shadow mode — intercept and log tool calls without forwarding; dry-run risky operations
• Payload filtering — block or redact sensitive patterns; encoding-aware (Base64, percent-encoding, Unicode)
• Response filtering — block upstream responses containing sensitive patterns
• Schema validation — validate tools/call arguments against inputSchema from tools/list
• OPA/Rego policy engine — evaluate every tools/call against a Rego policy file; input exposes agent, tool, arguments, and client IP
• Supply-chain security — verify MCP server binaries via SHA-256 or cosign before spawning (stdio mode)
• Audit log — every request recorded with X-Request-Id; fan-out to SQLite, webhook, stdout, or OpenLineage
• CloudEvents — webhook audit can emit CNCF CloudEvents 1.0 for direct SIEM ingestion
• Tool Federation — aggregate tools from multiple upstreams into a single view
• OpenAI Tools Bridge — /openai/v1/tools and /openai/v1/execute for OpenAI function-calling clients
• Multiple upstreams — route different agents to different MCP servers
• Circuit breaker — automatic upstream failure isolation with half-open recovery
• Config hot-reload — reload on SIGUSR1, automatically every 30 seconds, or event-driven via Kubernetes ConfigMap watcher
• Lock-free rate limiting — GCRA algorithm via governor; O(1) per check, configurable burst allowance
• Metrics — Prometheus-compatible /metrics endpoint with cost/token estimation
• OpenTelemetry — export traces to any OTLP backend (Jaeger, Tempo, Honeycomb, Datadog)
• Dashboard — /dashboard audit viewer with per-agent filtering
• TLS / mTLS — optional HTTPS with mutual TLS agent authentication
• Transport agnostic — HTTP+SSE or stdio; same config, same policies
• Secrets-safe config — ${VAR} interpolation in YAML + ARBITUS_* env var overrides; compatible with K8s Secrets, Vault, External Secrets Operator
• Container-ready — multi-arch Docker image, Helm chart with sidecar pattern, graceful shutdown

Documentation

Starter policies

The examples/policies/ directory contains ready-to-copy configs for common agent setups:

Community

• Contributing — How to contribute, development setup, code quality requirements
• Code of Conduct — Standards for community behavior
• Security Policy — Reporting vulnerabilities, supported versions, security features
• Governance — Project roles, decision-making, becoming a maintainer

Quick start

Install

cargo install arbitus

Or download a pre-built binary from the releases page:

Or build from source:

git clone https://github.com/arbitusgateway/arbitus
cd arbitus
cargo build --release

Or use Docker:

docker pull ghcr.io/arbitusgateway/arbitus:latest
docker run --rm -p 4000:4000 -v $(pwd)/gateway.yml:/app/gateway.yml ghcr.io/arbitusgateway/arbitus:latest

Configure

cp gateway.example.yml gateway.yml

transport:
  type: http
  addr: "0.0.0.0:4000"
  upstream: "http://localhost:3000/mcp"

agents:
  cursor:
    allowed_tools: [read_file, list_directory]
    rate_limit: 30

  claude-code:
    denied_tools: [write_file, delete_file]
    rate_limit: 60

rules:
  block_patterns: ["password", "api_key", "secret"]

Or start from a stricter policy:

arbitus policy init claude-code --out gateway.yml

List all bundled starter policies:

arbitus policy list

Run

./arbitus gateway.yml

Agents connect to http://localhost:4000/mcp. The gateway enforces policies and forwards allowed requests to the upstream MCP server.

Validate config

./arbitus validate gateway.yml

Query audit log

./arbitus audit gateway-audit.db --agent cursor --outcome blocked --since 1h

Architecture

            ┌──────────────────────────────────────────┐
            │                 Arbitus                  │
            │                                          │
  request ──► Pipeline                                 │
            │   1. RateLimitMiddleware                 │
            │   2. AuthMiddleware                      │
            │   3. HitlMiddleware    ← suspend & wait  │
            │   4. SchemaValidationMiddleware          │
            │   5. PayloadFilterMiddleware             │
            │         │                                │
            │    Allow / Block                         │
            │         │                                │
            │   Shadow mode check  ← mock if matched   │
            │         │                                │
            │   AuditLog + Metrics                     │
            │         │                                │
            │    McpUpstream (per-agent)               │
            └──────────────────────────────────────────┘

Tests

cargo test --all-features              # All tests
cargo test --lib                       # Unit tests only (no stdio/npx)
cargo test --test http_gateway         # Single integration test file

License

MIT