Introduction

I generated this repository using Claude Code after running into issues with the agent loop applifying hallucinated responses which led towards dangerous outcomes.

I didn't write it myself. It seems useful and worth sharing. Take it as you will. The rest of the text in this repo is AI-generated.

Arbiter: Firewall for MCP

A lightweight proxy that sits between AI agents and MCP (Model Context Protocol) servers, enforcing deny-by-default authorization, session budgets, drift detection, and structured auditing on every tool call.

Authorship. This codebase was written by Claude Opus 4.6 under human supervision, as a sanitized adaptation of a private research codebase. See AI_AUTHORSHIP.md.

Why?

AI agents act autonomously at machine speed. A single misconfigured agent can run DDL on production databases, export customer data, or escalate privileges, with nobody in the loop to stop it.

Applications like Claude Code let us define permissions. But that requires us to place trust in Claude Code, a closed source project, maintained by a corporation that operates non-transparently and is incentivized to push for more control over your computer, not less.

Arbiter is agnostic of development tooling and enforces:

What an agent can do (deny-by-default tool allowlists)
How much it can do (session time limits and call budgets)
Whether it should (drift detection: flags when tool-call operation types diverge from session scope)
That you'll know (structured audit trail of every decision)

See Why MCP Tool Calls Need a Firewall for the full argument, or the QuantumBank case study for a worked example showing 2 allowed and 4 blocked tool categories.

Limitations

Arbiter governs what agents are allowed to do. It does not govern what agents might try to do. It protects the platform by reducing the tool-call attack surface that agentic applications typically leave open, or require. This is valuable. But a clever-enough hacker with sinister-enough intentions will be able to deceive a model into hacking any proxy. That's a far deeper problem requiring greater compute than a proxy can performantly handle.

Who is Arbiter for?

Teams deploying AI agents over MCP that need per-tool-call access control they can self-host.

Arbiter is not an identity provider. It sits downstream of your IdP (Okta, Auth0, Keycloak) and enforces policy on what gets through. If you need centralized NHI management across hundreds of service identities, look at Aembit. If you need a managed platform, this isn't it. Arbiter is open-source infrastructure you operate yourself.

Trust model

Actor	Trust level	Rationale
Operator	Trusted	Configures Arbiter, writes policy files, manages agent registration
Policy file	Authoritative	Defines what tools are allowed; not validated for correctness
AI agent	Untrusted	Tool calls are intercepted, evaluated, and audit-logged before forwarding
Declared intent	Advisory	Used for drift detection, not enforcement; an adversarial agent would lie

Arbiter is designed for scenarios where the platform operator is trusted but the AI agents are not — the operator writes policy, the agents operate within it.

Disclaimers

This software is provided AS IS, with no warranty and no support. Use it at your own risk. There are no paid tiers, no license keys, and no gated features. Everything in this repository is free and open source under GPL-3.0-or-later.
Due to resource constraints, this project is currently managed agentically, under close human supervision. Take that as you will.

Sponsor

This is free software with no paid tiers. If you get value from it and want to help keep it going, consider sponsoring.

Sponsor on GitHub

Features

Agent identity & delegation. Register agents with trust levels and capabilities; delegate to sub-agents with narrowed scope; cascade deactivation
Deny-by-default authorization: policy engine that evaluates agent identity, session context, tool name, and parameter constraints
Task sessions. Time-limited, budget-capped, tool-whitelisted sessions per task
Drift detection: flags or blocks when tool-call operation types diverge from session scope (e.g., write calls during a read-scoped session)
OAuth 2.1 JWT validation. JWKS caching, multi-issuer support, token introspection fallback
MCP protocol parsing: extracts tool names, arguments, and resource URIs from JSON-RPC bodies
Structured audit logging. JSONL audit trail with automatic argument redaction for sensitive fields
Prometheus metrics: request counts, tool call counts, latency histograms, active sessions gauge
Environment-based secrets. Admin API key and token signing secret loaded from ARBITER_ADMIN_API_KEY and ARBITER_SIGNING_SECRET environment variables; startup warnings when defaults are detected; constant-time API key comparison to prevent timing side-channels
Per-agent session cap: configurable max_concurrent_sessions_per_agent (default 10) prevents session multiplication attacks where a single agent opens many sessions to bypass per-session rate limits
Credential scrubbing. When credential injection is active, upstream responses are scanned for the exact secrets Arbiter injected (in multiple encodings: plaintext, URL-encoded, JSON-escaped, hex, base64) and replaced with [CREDENTIAL] before the agent sees them

Architecture

Agent ──▶ Arbiter Proxy (:8080) ──▶ MCP Server
              │
              ├── Middleware chain: tracing → metrics → audit → oauth
              │   → mcp-parse → session → policy → behavior → forward
              │
              └── Admin API (:3000): agent registration, delegation, tokens

See Architecture for the full middleware chain, crate dependency graph, and data flow.

Install

curl -sSf https://raw.githubusercontent.com/cyrenei/arbiter-mcp-firewall/main/install.sh | sh

Downloads the latest binary for your platform (Linux/macOS, amd64/arm64) with SHA256 verification. Installs both arbiter and arbiter-ctl. No sudo required. The installer will offer to generate a config file interactively.

To generate a config file separately:

curl -sSf https://raw.githubusercontent.com/cyrenei/arbiter-mcp-firewall/main/configure.sh | sh

To update an existing installation:

arbiter-ctl update

Quickstart

Binary install (fastest):

curl -sSf https://raw.githubusercontent.com/cyrenei/arbiter-mcp-firewall/main/install.sh | sh
# Follow the config wizard, then:
arbiter --config arbiter.toml

Docker (full stack with mock MCP server):

docker compose up --build -d
curl http://localhost:8080/health           # -> OK
curl -X POST http://localhost:3000/agents \
  -H "x-api-key: arbiter-dev-key"          \
  -H "Content-Type: application/json"       \
  -d '{"owner":"user:alice","model":"gpt-4","capabilities":["read"],"trust_level":"basic"}'

Full walkthrough: Quickstart

Configuration

Single TOML file. The fastest way to generate one:

curl -sSf https://raw.githubusercontent.com/cyrenei/arbiter-mcp-firewall/main/configure.sh | sh

Or write it by hand. Here's the minimal viable config:

[proxy]
upstream_url = "http://your-mcp-server:8081"

[admin]
api_key = "your-secure-api-key"           # or set ARBITER_ADMIN_API_KEY env var
signing_secret = "your-secure-secret"     # or set ARBITER_SIGNING_SECRET env var

Everything else has sensible defaults (sessions enabled, audit on, deny-by-default policies). See arbiter.example.toml for the full reference with all sections documented.

Policy Language

[[policies]]
id = "allow-read-basic"
effect = "allow"
allowed_tools = ["read_file", "list_dir"]

[policies.agent_match]
trust_level = "basic"

[policies.intent_match]
keywords = ["read", "analyze"]

Full reference: Policy Language

Project Structure

crates/
├── arbiter/            Integration binary; wires everything together
├── arbiter-proxy/      Async HTTP reverse proxy with middleware chain
├── arbiter-oauth/      OAuth 2.1 JWT validation middleware
├── arbiter-identity/   Agent identity model and in-memory registry
├── arbiter-lifecycle/  Agent lifecycle REST API (axum)
├── arbiter-cli/        CLI for agent management
├── arbiter-mcp/        MCP JSON-RPC request parser
├── arbiter-policy/     Deny-by-default policy engine
├── arbiter-session/    Task session management
├── arbiter-behavior/   Drift detection
├── arbiter-metrics/    Prometheus-compatible metrics
└── arbiter-audit/      Structured audit logging with redaction

Building from Source

cargo build --release
./target/release/arbiter --config arbiter.toml --log-level info

Status

The core enforcement pipeline (policy engine, session management, drift detection, audit logging) is complete and tested. The QuantumBank scenario demonstrates end-to-end enforcement across 6 tool categories.

This project is provided as-is.

License

GPL-3.0-or-later. All of it. See LICENSE.

The proxy, the admin API, the policy engine, the audit pipeline, the arbiter-ctl CLI — every crate in this workspace is GPL-3-or-later. If you embed Arbiter in a larger system, link against its crates, ship a product that depends on it, or fork it into something else, you ship under GPL-3 too. That's the trade.

Releases v0.0.11 and earlier were published under Apache License 2.0. Starting with v0.1.0, the project is licensed under GPL-3.0-or-later. Prior releases retain their original Apache-2.0 terms; the license change applies to the v0.1.0 codebase and all subsequent work. Inbound contributions are accepted under the project's outbound license (GPL-3.0-or-later).

Workspace-level declaration: the root Cargo.toml carries license = "GPL-3.0-or-later", inherited by every crate via license.workspace = true.

Support

GitHub Issues, no SLA, no guaranteed response time.

Contact: cyrenei@proton.me

PGP Public Key

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github		.github
.minisign		.minisign
crates		crates
demos		demos
deploy		deploy
docker		docker
docs		docs
templates		templates
.gitignore		.gitignore
AI_AUTHORSHIP.md		AI_AUTHORSHIP.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
arbiter.example.toml		arbiter.example.toml
audit.toml		audit.toml
configure.sh		configure.sh
docker-compose.e2e.yml		docker-compose.e2e.yml
docker-compose.yml		docker-compose.yml
install.sh		install.sh
tarpaulin.toml		tarpaulin.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Introduction

Arbiter: Firewall for MCP

Why?

Limitations

Who is Arbiter for?

Trust model

Disclaimers

Sponsor

Features

Architecture

Install

Quickstart

Configuration

Policy Language

Project Structure

Building from Source

Status

License

Support

PGP Public Key

About

Uh oh!

Releases 35

Sponsor this project

Uh oh!

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Introduction

Arbiter: Firewall for MCP

Why?

Limitations

Who is Arbiter for?

Trust model

Disclaimers

Sponsor

Features

Architecture

Install

Quickstart

Configuration

Policy Language

Project Structure

Building from Source

Status

License

Support

PGP Public Key

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 35

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages