# mcp-airlock

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 15
- Author: Shalimov04
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Shalimov04/mcp-airlock
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-airlock

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `AIRLOCK_JWT_SECRET`, `AIRLOCK_SECRET` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> --env AIRLOCK_SECRET=<AIRLOCK_SECRET> --transport stdio mcp-airlock -- uvx mcp-airlock
```
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>

### Codex

**Platform CLI**
```bash
codex mcp add mcp-airlock --env AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> --env AIRLOCK_SECRET=<AIRLOCK_SECRET> -- uvx mcp-airlock
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e AIRLOCK_JWT_SECRET=<AIRLOCK_JWT_SECRET> -e AIRLOCK_SECRET=<AIRLOCK_SECRET> mcp-airlock uvx mcp-airlock
```
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>

## When to use it
- 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
- Ask `mcp-airlock` to inspect a delete-tool call for `prod` and 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-airlock` filters `tools/list`.

## Similar
- [k8s-manifest-generator](https://affpapa.org/en/nevibecode/skills/k8s-manifest-generator.md) — skill · 11166 installs
- [ci-cd-security](https://affpapa.org/en/nevibecode/skills/ci-cd-security.md) — skill · 7900 installs
- [dependabot](https://affpapa.org/en/nevibecode/skills/dependabot.md) — skill · 4400 installs
- [github-actions-hardening](https://affpapa.org/en/nevibecode/skills/github-actions-hardening.md) — skill · 2200 installs
- [ansible-validator](https://affpapa.org/en/nevibecode/skills/ansible-validator.md) — skill · 1300 installs
- [gitlab-ci-validator](https://affpapa.org/en/nevibecode/skills/gitlab-ci-validator.md) — skill · 679 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md