mcp-airlock MCP server

mcp-airlock

Русская версия

mcp-airlock is a proxy you put between an AI agent and an MCP server when the server can do things you don't want an agent doing on its own. It speaks the 2026-07-28 revision of the protocol (the stateless one: no session, no initialize, one POST per request) and adds the parts the protocol leaves to you: who is allowed to call what, dry runs by default, a human in the loop for dangerous calls, an audit trail and tracing.

It is deliberately small. There is no UI, no policy language beyond flat YAML, no MCP SDK of its own. The whole proxy is one Starlette app plus a few helper modules.

How a call goes through

The agent sends a normal tools/call to the proxy instead of the server. The proxy:

it behind a gateway that already did the authentication, from an X-Airlock-Principal header. It is never taken from the request body. No principal, no call.

1. Works out who is calling. That comes from a JWT (Authorization: Bearer) or, if you run

a risk tier per environment, so the same delete_service can be free in dev and gated in prod.

1. Looks the tool up in the policy. Tools that are not listed are refused. Listed tools have

1. Depending on the tier:

agent as input_required with a description of what would happen and a signed requestState. When a person says yes, the agent repeats the call with that state and the proxy executes it for real, once. Repeating it again is refused.

• L0 (read) goes straight through.
• L1 (suggest) always goes through with dry_run: true, whatever the agent asked for.
• L2 (confirm) goes through with dry_run: true first, and the result comes back to the

• L3 (auto) goes through as sent.

argument you name in the policy) and how many a principal has touched in the last hour or day.

1. Checks the blast radius: how many objects one call touches (the length of a list

anything in it that smells like a prompt injection. Marking only; it does not change what the agent gets to see.

1. Forwards the call, cuts the response down to the output cap if it is too big, and marks

1. Writes two audit records, one before the upstream call and one after, whatever happened.

Refusals come back as tool results with isError: true, not as protocol errors, so the model sees why and can do something else. Every result carries the verdict and the rule that produced it in _meta.

Running it

The released version, no clone needed:

uvx mcp-airlock --policy policy.yaml --upstream http://127.0.0.1:8080/mcp --env prod

The same as a container. The image listens on 0.0.0.0:9000, runs as a non-root user and writes audit.jsonl into /data:

docker run --rm -p 9000:9000 -v $PWD/policy.yaml:/data/policy.yaml \
  ghcr.io/shalimov04/mcp-airlock:0.2 --policy policy.yaml --upstream http://host.docker.internal:8080/mcp --env prod

From a checkout:

uv sync
uv run pytest
uv run python demo.py

The demo starts a fake upstream with a handful of tools on port 9001 and the proxy on 9000, walks through the interesting cases (refused tool, forced dry run, confirmation, replay, blast radius, output cap, injection marking) and leaves the audit log and spans in examples/.

The short version, recorded against that same fake upstream. An agent tries to delete a production service, gets a dry run and a confirmation prompt instead, the confirmation works exactly once, and a poisoned read result comes back flagged:

docs/makedemogif.py re-records it (uv run --with pillow python docs/makedemogif.py).

docs/clients.md shows how to point Claude Code and Cursor at the proxy and what the agent sees when a call is refused or held for confirmation.

Against a real server:

Shortened. The full README is on GitHub.