MCPDome

Protective Dome for AI Agents — MCP Security Gateway

If you find MCPDome useful, consider giving it a star — it helps others discover the project!

Architecture · Example Policy · Changelog

Made by Orellius.ai

MCPDome sits between your AI agent and any MCP server, intercepting every JSON-RPC message on the wire. It enforces authentication, authorization, rate limiting, and injection detection — without modifying either side. Think of it as a firewall for AI tool calls.

┌──────────┐         ┌─────────┐         ┌────────────┐
│ AI Agent │ ──MCP──>│ MCPDome │──MCP──> │ MCP Server │
│ (Client) │<──MCP── │ Gateway │<──MCP── │  (Tools)   │
└──────────┘         └─────────┘         └────────────┘
                          │
                     ┌────┴────┐
                     │ Policy  │
                     │  TOML   │
                     └─────────┘

Why MCPDome?

AI agents are getting access to powerful tools — file systems, databases, APIs, code execution. MCP is the protocol connecting them. But there's no security layer in the middle. MCPDome fixes that:

• Default-deny policy engine — TOML rules with time-window conditions and day-of-week filtering, hot-reloadable via file watcher or SIGHUP
• Injection detection — Regex patterns with Unicode normalization (NFKC, homoglyph transliteration, zero-width stripping), recursive JSON scanning, and heuristic analysis (entropy, Base64, length)
• Schema pinning — Canonical SHA-256 hashes of tool definitions detect and block rug pulls and tool shadowing
• Hash-chained audit logs — Tamper-evident NDJSON logging with SHA-256 chain linking, full inbound + outbound coverage
• Token-bucket rate limiting — Global, per-identity, and per-tool limits with LRU eviction and TTL-based cleanup
• Multiple auth methods — Argon2id-hashed PSKs, API key authentication, OAuth2 scaffolding, with timing-safe verification and automatic credential stripping
• HTTP+SSE transport — Feature-gated HTTP transport with Server-Sent Events, session management, restricted CORS, and 256KB body limits — selectable via --transport http
• Bounded I/O — 10MB max message size, 5-minute read timeouts, 30-second write timeouts to prevent resource exhaustion
• Graceful shutdown — SIGTERM/SIGINT signal handling with clean child process termination (SIGTERM → wait → SIGKILL fallback), upstream command validation before spawn
• Full method coverage — All MCP methods are guarded (not just tools/call), with method-specific resource extraction (tool names, resource URIs, prompt names) for fine-grained policy rules
• Outbound scanning — Server responses are scanned for injection patterns before reaching the AI agent
• CLI toolbox — validate, verify-log, hash-schema, keygen subcommands plus unified --config file support
• 0.2ms overhead — Rust performance, single binary, zero config to start

Install

# From crates.io
cargo install mcpdome

# From source
git clone https://github.com/orellius/mcpdome.git
cd mcpdome
cargo build --release

Quick Start

Wrap any stdio MCP server — zero config, transparent mode:

mcpdome proxy --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"

Enable security features progressively:

# Injection detection
mcpdome proxy --upstream "..." --enable-ward

# Schema pinning (detect tool definition changes)
mcpdome proxy --upstream "..." --enable-schema-pin

# Rate limiting
mcpdome proxy --upstream "..." --enable-rate-limit

# Everything with a config file
mcpdome proxy --upstream "..." --config mcpdome.toml

# HTTP+SSE transport (instead of stdio)
mcpdome proxy --upstream "..." --transport http --bind-addr 127.0.0.1:3100

CLI Tools

# Validate a policy file
mcpdome validate policy.toml

# Verify audit log integrity
mcpdome verify-log audit.ndjson

# Pre-compute schema pin hashes
mcpdome hash-schema tools.json

# Generate a pre-shared key
mcpdome keygen

What It Catches

Policy Example

# Block secret patterns everywhere (highest priority)
[[rules]]
id = "block-secrets"
priority = 1
effect = "deny"
identities = "*"
tools = "*"
arguments = [
    { param = "*", deny_regex = ["AKIA[A-Z0-9]{16}", "ghp_[a-zA-Z0-9]{36}"] },
]

# Developers can read, not delete
[[rules]]
id = "dev-read-tools"
priority = 100
effect = "allow"
identities = { labels = ["role:developer"] }
tools = ["read_file", "grep", "git_status"]

# Write only to safe paths
[[rules]]
id = "dev-write-safe"
priority = 110
effect = "allow"
identities = { labels = ["role:developer"] }
tools = ["write_file"]
arguments = [
    { param = "path", allow_glob = ["/tmp/**"], deny_regex = [".*\\.env$"] },
]

Time-window conditions:

[[rules]]
id = "business-hours-only"
priority = 50
effect = "allow"
identities = "*"
tools = ["write_file", "delete_file"]
conditions = [
    { type = "time_window", after = "09:00", before = "17:00", timezone = "UTC" },
    { type = "day_of_week", days = ["Mon", "Tue", "Wed", "Thu", "Fri"] },
]

See mcpdome.example.toml for a complete policy file.

Architecture

Rust workspace of focused crates, each with a single responsibility:

mcpdome (binary)
  ├── dome-core         Shared types & error taxonomy
  ├── dome-transport    MCP wire protocol (stdio, HTTP+SSE)
  ├── dome-gate         Interceptor chain orchestration
  ├── dome-sentinel     Authentication & identity resolution
  ├── dome-policy       TOML policy engine (default-deny)
  ├── dome-ledger       Hash-chained audit logging
  ├── dome-throttle     Token-bucket rate limiting & budgets
  └── dome-ward         Injection detection & schema pinning

Interceptor chain order (inbound):

sentinel → throttle → ward → policy → ledger → upstream server

Ward runs before policy so injection detection cannot be bypassed by overly permissive authorization rules.

See ARCHITECTURE.md for the full deep dive.

Test Suite

235 tests covering every security component:

dome-core       10 tests   (message parsing, error mapping, resource/prompt extraction)
dome-gate       23 tests   (config defaults, interceptor chain, audit recording, Debug impl, constants)
dome-sentinel   30 tests   (PSK auth, API keys, Argon2id, timing-safe verification, chain resolution)
dome-policy     39 tests   (rules, priority, recursive args, time-windows, hot-reload, concurrent reads)
dome-throttle   22 tests   (token bucket, rate limits, budgets, LRU eviction, global limits, TOCTOU safety)
dome-ward       56 tests   (injection patterns, Unicode normalization, recursive scanning, schema pins, heuristics)
dome-ledger     21 tests   (hash chain, tamper detection, file rotation, chain integrity validation)
mcpdome binary  22 tests   (CLI subcommands, upstream validation, verify-log, hash-schema, keygen)
dome-transport   5 tests   (HTTP+SSE: connection, roundtrip, CORS, session cleanup, 404)
integration      7 tests   (full binary proxy end-to-end)

cargo test --workspace

Roadmap

| Phase | What Ships | Status | |-------|-----------|--------| | 1 | Transparent stdio proxy, audit logging | Done | | 2 | TOML policy engine, PSK authentication, default-deny | Done | | 3 | Injection detection, schema pinning, rate limiting | Done | | 4 | HTTP+SSE transport, API key auth, time-window policies, config hot-reload, CLI tools | Done | | 5 | OAuth 2.0 / mTLS, dashboard UI, remote policy fetching | Next |

License

Apache-2.0

Author

Orel Ohayon / Orellius.ai