mcp-airlock — Claude Code MCP server: use and install
A policy proxy controls MCP calls from an AI agent, forcing dry runs and human approval for risky actions. Use it when server-side guardrails matter.
claude mcp add --env AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> --env AIRLOCK_SECRET=<AIRLOCK_SECRET> --transport stdio mcp-airlock -- uvx mcp-airlockWhat mcp-airlock does
mcp-airlock sits between an agent and an MCP server and applies a YAML policy to each call. Unlisted tools are rejected. Risk levels can vary by environment: read calls pass through, suggest calls are forced into dry-run mode, and confirm calls return a signed state before a person approves execution. Reusing that approved state is refused.
The proxy identifies callers with a JWT or a trusted X-Airlock-Principal header. It checks blast radius, trims oversized responses, and marks possible prompt-injection content without changing the payload. Each call produces audit records before and after the upstream request. JSONL works in the base setup; Postgres needs the postgres extra, regex rules need regex, and OTLP export needs otlp.
Without a JWT or trusted principal header, calls receive HTTP 401. The server handles tools/call, tools/list, and server/discover; other methods are rejected. It is a small Starlette app with no UI and no separate policy language.
What it helps with
- restrict MCP tools with a YAML policy
- force risky calls into dry-run mode
- require approval before production actions
- cap the number of affected objects
- record audits around upstream calls
Example prompts for the agent
- Ask
mcp-airlockto inspect a delete-tool call forprodand return its dry-run result. - Run an allowed MCP call through
mcp-airlock, check its blast radius, and report the policy verdict. - Show which tools remain visible after
mcp-airlockfilterstools/list.
How to install mcp-airlock
Platform CLI
claude mcp add --env AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> --env AIRLOCK_SECRET=<AIRLOCK_SECRET> --transport stdio mcp-airlock -- uvx mcp-airlockReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-airlock <command>
Platform CLI
codex mcp add mcp-airlock --env AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> --env AIRLOCK_SECRET=<AIRLOCK_SECRET> -- uvx mcp-airlockReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-airlock <command>
Config file
{
"mcpServers": {
"mcp-airlock": {
"command": "uvx",
"args": [
"mcp-airlock"
],
"env": {
"AIRLOCK_JWT_SECRET": "<AIRLOCK_JWT_SECRET>",
"AIRLOCK_SECRET": "<AIRLOCK_SECRET>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-airlock <command>
Config file
{
"servers": {
"mcp-airlock": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-airlock"
],
"env": {
"AIRLOCK_JWT_SECRET": "<AIRLOCK_JWT_SECRET>",
"AIRLOCK_SECRET": "<AIRLOCK_SECRET>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-airlock <command>
Platform CLI
gemini mcp add -e AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> -e AIRLOCK_SECRET=<AIRLOCK_SECRET> mcp-airlock uvx mcp-airlockReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-airlock <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-airlock
How do I install mcp-airlock in Claude Code?
Run claude mcp add --env AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> --env AIRLOCK_SECRET=<AIRLOCK_SECRET> --transport stdio mcp-airlock -- uvx mcp-airlock.
What does mcp-airlock do?
It proxies MCP traffic and applies per-tool risk rules. The proxy can force dry runs, require approval, check blast radius, and write audit records.
What does mcp-airlock need to authenticate calls?
Use a JWT or a trusted X-Airlock-Principal header. Postgres storage requires the postgres extra, while regex policy rules require regex.
