mcpdome 0.3.0

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 automatic credential stripping
• HTTP+SSE transport — Feature-gated HTTP transport with Server-Sent Events, session management, and CORS support (in addition to stdio)
• Full method coverage — All MCP methods are guarded (not just tools/call), with proper JSON-RPC error responses on deny
• 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

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

204 tests covering every security component:

dome-core        5 tests   (message parsing, error mapping)
dome-sentinel   30 tests   (PSK auth, API keys, Argon2id, OAuth2 stub, chain resolution)
dome-policy     39 tests   (rules, priority, recursive args, time-windows, hot-reload)
dome-throttle   22 tests   (token bucket, rate limits, budgets, LRU eviction, global limits)
dome-ward       56 tests   (injection patterns, Unicode normalization, recursive scanning, schema pins, heuristics)
dome-ledger     21 tests   (hash chain, tamper detection, file rotation)
dome-transport   5 tests   (HTTP+SSE connection, roundtrip, CORS, cleanup)
mcpdome binary  19 tests   (CLI subcommands: validate, verify-log, hash-schema, keygen)
integration      7 tests   (full binary proxy end-to-end)

cargo test --workspace

Roadmap

License

Apache-2.0

Author

Orel Ohayon / Orellius.ai