Skip to main content
Glama
mcp-airlock

mcp-airlock

by sigma5667

πŸ›‘οΈ Airlock for MCP

Governance for the rest of us. A zero-infra, local proxy that wraps any stdio MCP server and adds the three things the protocol leaves out: an audit ledger, policy enforcement, and budget guards β€” with zero dependencies and no gateway, account, or hosting.

client ──stdio──▢  πŸ›‘οΈ airlock  ──stdio──▢  any MCP server
                    β”‚
                    β”œβ”€ audit ledger (JSONL)
                    β”œβ”€ policy: allow/deny + regex arg guards
                    └─ budgets: per-session / per-day

Airlock for MCP is an independent project and is not affiliated with or endorsed by Anthropic, the Model Context Protocol, or the Linux Foundation. See NOTICE.

Why

AI agents are being wired into everything, but oversight lags: 82% of organizations report using AI agents while only 44% have a security policy for them (SailPoint, AI Agent Adoption Report, 2025). Meanwhile the local MCP servers behind Claude Code / Cursor / Claude Desktop run outside any enterprise gateway β€” no audit trail, no guardrails.

There are heavy enterprise gateways (MintMCP, MCP Manager, TrueFoundry) and a growing set of OSS tools in this space. Airlock is the zero-infra, local-first, zero-dependency option: drop it in front of a server you already use and get an audit trail + policy + budgets in seconds β€” no account, no hosting, nothing leaves your machine. See MARKET_GAP.md.

Related MCP server: mcp-doorman

Install

pip install mcp-airlock          # zero runtime dependencies; installs the `airlock` command
# or run straight from source:
PYTHONPATH=src python -m mcp_airlock --help

Use β€” wrap any server with one line

Anywhere you launch an MCP server, put airlock … -- in front of it.

Before (claude_desktop_config.json / .mcp.json):

{ "mcpServers": {
  "db": { "command": "npx", "args": ["-y", "@some/db-mcp-server"] }
}}

After β€” same server, now governed:

{ "mcpServers": {
  "db": {
    "command": "airlock",
    "args": ["--config", "policy.json", "--ledger", "db.ledger.jsonl",
             "--", "npx", "-y", "@some/db-mcp-server"]
  }
}}

That's it. The downstream server is unchanged; the client sees the same tools (plus one: airlock_report).

Policy (policy.json)

{
  "default": "allow",
  "redact": ["password", "token", "api_key", "secret"],
  "rules": [
    { "tool": "Bash", "action": "allow",
      "deny_args_matching": ["rm\\s+-rf\\s+/", "curl[^\\n]*\\|\\s*(sh|bash)"] },
    { "tool": "delete_*", "action": "deny" },
    { "tool": "*", "action": "allow" }
  ],
  "budgets": {
    "per_session": { "Bash": 100, "*": 1000 },
    "per_day":     { "*": 5000 }
  }
}
  • rules are evaluated in order; the first rule whose tool glob matches decides.

  • deny_args_matching β€” regexes tested against the JSON-serialized arguments; any hit turns an allow into a deny before the call reaches the server. Ship-blocked by default: rm -rf /, dd if=, mkfs, fork bombs, curl … | sh.

  • allow_args_matching β€” if present, args must match at least one regex.

  • redact β€” keys whose values are replaced with ***REDACTED*** in the ledger (recursively). Secrets never touch disk.

  • budgets β€” per-tool call caps; * is the wildcard. Breach β†’ hard block.

The audit ledger

Append-only JSONL β€” one call per line. Tail it, grep it, or pipe it into any log stack:

{"ts":"2026-07-01T09:12:04Z","session":"sess-ab12","event":"call","tool":"delete_record","decision":"deny","status":"blocked","args":{"id":"42"},"reason":"denied by rule 'delete_*'"}
{"ts":"2026-07-01T09:12:07Z","session":"sess-ab12","event":"call","tool":"echo","decision":"allow","status":"ok","args":{"text":"hi"},"duration_ms":3.1}

airlock_report β€” the agent can audit itself

Airlock injects one extra tool into tools/list. Ask the agent to call it (or call it yourself) for a live summary:

Airlock β€” audit summary
  total calls   : 132
  allowed       : 128
  blocked       : 4
  avg duration  : 41.7 ms
  top tools:
     71x  read_file
     38x  Bash
  blocks:
      3x  denied by rule 'delete_*'
      1x  argument guard matched /rm\s+-rf\s+\// on rule 'Bash'

How it works

A transparent newline-delimited JSON-RPC 2.0 proxy. It spawns the downstream server as a child process and forwards every frame unchanged, except:

Intercepted

Action

tools/list response

injects the airlock_report tool

tools/call request

policy + budget check before forwarding; blocks return an isError result

airlock_report call

answered locally from the ledger

Everything else β€” initialize, resources, prompts, notifications β€” passes through byte-for-line. Non-JSON stdout from a misbehaving server is dropped to stderr so it can't corrupt the client stream.

Test

pip install pytest
PYTHONPATH=src python -m pytest tests/ -q

Design principles

  1. Zero dependencies β€” Python stdlib only. Audit the whole thing in one sitting.

  2. Transport-transparent β€” works with any stdio MCP server, unchanged.

  3. Local-first β€” no gateway, no account, no data leaves your machine.

  4. Fail-safe β€” a policy parse error refuses to start; it never silently allows.

License

MIT β€” see LICENSE. Provided "as is", including for any tool call it allows or blocks.

Available Tools

17 tools
airlock_reportA

Return a live audit summary from Airlock: total/allowed/blocked calls, top tools, block reasons and recent errors. Injected by the local governance proxy.

Inputs: limit, session_only.

echoEcho ToolB
Read-onlyIdempotent

Echoes back the input string

Inputs: message (required).

get-annotated-messageGet Annotated Message ToolC
Read-onlyIdempotent

Demonstrates how annotations can be used to provide metadata about content.

Inputs: messageType (required), includeImage.

get-envPrint Environment ToolA
Read-onlyIdempotent

Returns all environment variables, helpful for debugging MCP server configuration. Values of credential-like names (a KEY, TOKEN, SECRET, PASSWORD, PASSWD, CREDENTIAL, AUTH or COOKIE name segment) are masked as "" unless GET_ENV_INCLUDE_SECRETS is set to 1 or true in the server's environment.

Inputs: no named parameters.

get-header-paramsGet Header Params ToolA
Read-onlyIdempotent

Returns its region argument and the Mcp-Param-Region HTTP header it arrived in. Demonstrates x-mcp-header (a 2026-07-28 Streamable HTTP client mirrors the argument into the header) and JSON Schema 2020-12 input and output schemas.

Inputs: region (required), repeat. Returns: region, repeated, regionHeader

get-resource-referenceGet Resource Reference ToolC
Read-onlyIdempotent

Returns a resource reference that can be used by MCP clients

Inputs: resourceId, resourceType.

get-structured-contentGet Structured Content ToolC
Read-onlyIdempotent

Returns structured content along with an output schema for client data validation

Inputs: location (required). Returns: humidity, conditions, temperature

get-sumGet Sum ToolB
Read-onlyIdempotent

Returns the sum of two numbers

Inputs: a (required), b (required).

get-tiny-imageGet Tiny Image ToolA
Read-onlyIdempotent

Returns a tiny MCP logo image.

Inputs: no named parameters.

gzip-file-as-resourceGZip File as Resource ToolA
Idempotent

Compresses a single file using gzip compression. Depending upon the selected output type, returns either the compressed data as a gzipped resource or a resource link, allowing it to be downloaded in a subsequent request: during the current session for a 2025-era client, or for ten minutes at a minted URI on protocol version 2026-07-28.

Inputs: data, name, outputType.

toggle-simulated-loggingToggle Simulated LoggingA

Toggles simulated, random-leveled logging on or off. Deprecated: 2025-era clients only, since protocol version 2026-07-28 removes logging/setLevel; use trigger-log-messages with a per-request log level instead.

Inputs: no named parameters.

toggle-subscriber-updatesToggle Subscriber UpdatesA

Toggles simulated resource subscription updates on or off. Deprecated: 2025-era clients only, since protocol version 2026-07-28 removes resources/subscribe; use trigger-resource-update with a subscriptions/listen stream instead.

Inputs: no named parameters.

trigger-list-changedTrigger List Changed ToolA
Read-only

Sends a notifications//list_changed for the tool, prompt or resource list. On protocol version 2026-07-28 it is delivered on each subscriptions/listen stream that asked for that list; a 2025-era client receives it unsolicited.

Inputs: list (required).

trigger-log-messagesTrigger Log Messages ToolA
Read-onlyIdempotent

Sends one log message at each logging level during the call. On protocol version 2026-07-28 only the messages at or above the level the request names in _meta (io.modelcontextprotocol/logLevel) are sent, and none if it names no level; a 2025-era client gets those at or above the level it set with logging/setLevel. Deprecated: logging is deprecated as of protocol version 2026-07-28.

Inputs: no named parameters.

trigger-long-running-operationTrigger Long Running Operation ToolC
Read-onlyIdempotent

Demonstrates a long running operation with progress updates.

Inputs: steps, duration.

trigger-resource-updateTrigger Resource Update ToolA
Read-only

Sends a notifications/resources/updated for a resource URI. On protocol version 2026-07-28 it is delivered on each subscriptions/listen stream whose resourceSubscriptions name the URI; a 2025-era client receives it once it has called resources/subscribe for the URI.

Inputs: uri (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 17 tools

    Disambiguation3/5

    Most tools map to a distinct MCP protocol feature, but several pairs overlap in intent: trigger-log-messages vs toggle-simulated-logging, trigger-resource-update vs toggle-subscriber-updates, and get-resource-links vs get-resource-reference. The descriptions do explain the deprecated/demo distinction, and airlock_report is a completely different (governance/audit) purpose bolted onto a protocol-demo surface, which muddies what the server is for.

    Naming Consistency4/5

    Nearly everything follows a kebab-case verb_noun or get-* pattern (get-env, get-sum, trigger-list-changed, toggle-subscriber-updates, gzip-file-as-resource). The only deviation is airlock_report using snake_case, which is a minor but visible inconsistency.

    Tool Count3/5

    17 tools sits at the heavy end for a demo/protocol-conformance server, and two of them (toggle-simulated-logging, toggle-subscriber-updates) are explicitly deprecated duplicates of trigger-* equivalents. Each remaining tool does demonstrate a separate capability, so it is defensible but not tight.

    Completeness3/5

    Coverage of tools/annotations/structured content/resources/logging/notifications is broad, but there is no prompt demo, no sampling or elicitation demo, and no tool to actually read or list resources despite the resource-link and resource-update tools. For a server whose apparent purpose is exercising the full MCP surface, these are notable gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Security gateway that wraps any MCP server with per-tool policies, approval gates, and optional Ed25519-signed decision receipts. Shadow mode logs every tool call without blocking; enforce mode applies block, rate-limit, and minimum-tier rules. Receipts are independently verifiable offline with no accounts needed.
      5
      2,368 npm
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A drop-in proxy that guards MCP servers with policy enforcement, secret redaction, prompt-injection screening, rug-pull detection, rate limiting, and audit logging.
      7 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Zero-dependency local proxy that wraps any MCP server to redact secrets, strip hidden-Unicode prompt injection, and block writes to protected paths like ~/.ssh and .env.
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Sits in front of any MCP server to enforce allow/ask/block policies on tool calls, paths, shell commands, and network domains, with local approval prompts and an audit log.
      MIT