Projects are where ideas prove whether they can survive contact with use.

Back to projects

Countersign: Putting a Person Between AI Agents and Their Tools

Featured project

Local MCP gave one AI agent access to my machine. Countersign controls what a whole team's agents can do: who they are, which tools they may call, and which calls need a person to approve them.

9 min read
MCP
AI Agents
Security
TypeScript
PostgreSQL
Keycloak
Docker
Terraform
AWS

Countersign: Putting a Person Between AI Agents and Their Tools

When I wrote about Local MCP, I ended with a confession. Security was the part I knew needed more thinking. One shared token, no per-tool permissions, a shell tool that runs real commands. Fine for my own laptop. Not fine for anything else.

So I went back to it, and the problem got bigger than my laptop.

AI agents now open tickets, push code, and query databases with real credentials. On most teams, anyone can plug a new tool server into their assistant without telling anyone. Keys get copied onto every machine that needs them. And when an agent decides to delete a branch, nobody is asked first.

If something goes wrong, most teams cannot say which agent did it, which rule allowed it, or who approved it.

I built Countersign to answer those three questions for every call.

A new team goes from nothing to approving its first agent action, clicked through the real dashboard.

The video covers eight steps:

  • 0:04 The platform operator creates an organisation
  • 0:19 The owner joins from a one-time invite
  • 0:35 They connect a tool server (DeepWiki)
  • 0:54 They register an agent
  • 1:07 They set each tool's risk
  • 1:16 The agent asks for something risky, and a person approves it
  • 1:26 The audit log proves nothing was changed
  • 1:34 They invite a teammate

What Countersign is

Countersign is a self-hosted gateway that sits between AI agents and the MCP servers they use.

Agents do not talk to GitHub, Jira, or a shell directly anymore. They talk to one endpoint. Behind it, Countersign decides who is calling, whether the rules allow it, and whether a person needs to say yes first. Then it makes the call with credentials the agent never sees, and writes everything down.

It is multi-tenant. One install can serve many organisations, and each one has its own tools, agents, people, rules, and audit log.

The name comes from banking. A countersignature is a second signature that confirms the first. In Countersign, the agent makes the request and a person signs off on the risky ones.

How a call flows

Agent (Claude Code, a CI job, a script)
        │  POST /mcp  + OAuth token
        â–¼
  Countersign gateway
        │
        ├── 1. Who is calling?        Keycloak token → tenant + agent
        ├── 2. Is it allowed?         Cedar policy, per tenant
        ├── 3. Does a person approve? HIGH risk → held until someone decides
        ├── 4. Run it safely          tenant's credentials, or a sandbox
        └── 5. Record it              hash-chained audit log
        │
        â–¼
  MCP servers (GitHub, Jira, DeepWiki, your own)

A denied or unapproved call stops at the gateway. It never reaches the server.

The pieces

Identity. Every agent and every person gets their own sign-in through Keycloak. CI jobs use client credentials. People using Claude Code sign in through the browser. Each token maps to exactly one tenant and one agent. Suspend an agent and it is cut off within seconds.

Rules. Every tool has a risk level: low, medium, or high. Policies decide which agent may see and call what. I used Cedar for this instead of OPA. The deciding reason was that tenants write their own policies, so the language had to be safe to accept from strangers: no loops, no I/O, nothing that can reach another tenant. Default deny and "any forbid beats every permit" are built into the engine, not left to how each tenant writes rules. Bad policies are rejected when they are saved, not when an agent hits them. Every change is a new version you can compare and roll back.

Approvals. A high-risk call is stored as pending and the gateway holds the agent's request open, for up to two minutes, while a person reviews it in the dashboard. They see the exact arguments the agent sent. They approve or reject, and the waiting agent gets its answer.

The other option was to fail the call and make the agent retry later. I did not go with it because most agents do not handle "try again later" well. They give up, or they call again in a loop. Holding the request open means the agent just calls the tool and waits for the result.

A sandbox for code. Agents that want to run shell commands or Python get a fresh container for every call, under gVisor where the machine has it. No network. A read-only filesystem. Hard limits on CPU, memory, and time. Deleted afterwards. The service that starts these containers never touches the Docker socket directly; a small guard sits in front of it and only allows the exact container shape the sandbox needs.

Credentials. Each organisation stores its own keys for its tool servers. They are envelope-encrypted, decrypted only for the call that needs them, and redacted from anything that comes back. The agent only ever sees the result of the call, never the key.

The audit log. Every decision and every admin change goes into a log where each entry carries the hash of the one before it. Edit or remove anything and the chain breaks. Because someone with database access could rebuild a whole new chain, the newest hash is also written somewhere the database cannot reach: a separate volume locally, or an S3 bucket with Object Lock on AWS. One click in the dashboard recomputes the whole thing.

Tenant isolation. Organisations are kept apart by Postgres row-level security, forced on every table. The application sets the tenant on each transaction, and the database itself refuses to return another tenant's rows. So even if a query in my code forgets to filter by tenant, it still only returns that tenant's rows.

Attacking my own work

I also wrote tests whose only job is to break those defences. The repository has an attack suite that runs on every change. It covers tenant isolation, default deny, credential redaction, token passthrough, sandbox escapes, approval abuse, audit tampering, noisy neighbours, argument abuse, and suspension. 144 tests, each one trying to do something the system should not allow.

The sandbox tests run real attacks inside real containers: reaching the internet or the Docker host, reading host files, a fork bomb, filling the disk, eating memory, becoming root. Under every runtime Docker has on the machine. Then they check that no container was left behind.

There is also a threat model, written early, before most of the code, and every major decision has its own short write-up explaining what I chose and what I gave up.

Numbers

I load tested it with k6. These are the results in the repo:

  • 16 ms added at p95, at 50 calls per second
  • 22 ms p95 for one organisation while another floods the gateway at five times its limit. The flooding organisation's extra calls are refused with a 429 instead of slowing everyone else down.
  • 155 AWS resources created and destroyed by Terraform in about two minutes, against a local AWS emulator, in CI on every change

There is a ceiling too. On a single machine the gateway handles around 100 calls per second well. At 200 the slowest calls take over half a second, and at 300 it is saturated. That is the limit I measured on one machine.

Try it yourself

The code is private, but the release is not. You can install and run Countersign on your own machine in a few minutes.

What you need: Docker with Compose v2.17 or later (Docker Desktop on macOS and Windows, Docker Engine on Linux), about 2 GB of memory for Docker, and 3 GB of disk for the images. It runs on x86 and ARM, including Apple silicon.

Linux and macOS:

curl -LO https://www.mobasit.online/projects/countersign/agent-gateway-0.2.1.tar.gz
curl -LO https://www.mobasit.online/projects/countersign/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing   # on macOS: shasum -a 256 agent-gateway-0.2.1.tar.gz

tar xzf agent-gateway-0.2.1.tar.gz
cd agent-gateway-0.2.1
./install.sh

Windows (PowerShell):

Invoke-WebRequest https://www.mobasit.online/projects/countersign/agent-gateway-0.2.1.zip -OutFile agent-gateway-0.2.1.zip
Get-FileHash agent-gateway-0.2.1.zip   # compare with SHA256SUMS below

Expand-Archive agent-gateway-0.2.1.zip .
cd agent-gateway-0.2.1
powershell -ExecutionPolicy Bypass -File .\install.ps1

The checksums, if you want to compare by hand:

09f52c379b8d6a65ee09e0ca9395754f409fdbf05f975aa76a168b9fb3bbfe57  agent-gateway-0.2.1.tar.gz
32aa52e4fd0cb87ff627105d46ce12beba8635201661da0913854d9ea78936d2  agent-gateway-0.2.1.zip

The first start downloads the images, so give it a few minutes. The installer generates every secret, picks free ports, starts everything, and waits until it is healthy. At the end it prints the dashboard address (usually http://localhost:3000) and the MCP endpoint (usually http://localhost:8787/mcp).

It comes with two demo organisations already set up. The sign-ins are in ~/.agent-gateway/credentials.txt. Sign in to the dashboard as alice to look around as an organisation owner, or as operator to create a new organisation the way the video does.

To point Claude Code at it:

claude mcp add --transport http --client-id tenant-a-claude-code --callback-port 53682 \
  agent-gateway http://localhost:8787/mcp

Then run /mcp in Claude Code, pick agent-gateway, and sign in as alice when the browser opens. High-risk tools, like the sandbox, will wait for you to approve them under Approvals in the dashboard. Set MCP_TOOL_TIMEOUT above 120000 so Claude Code waits that long.

When you are done:

~/.agent-gateway/agw stop                      # stop it, keep the data
~/.agent-gateway/agw uninstall --purge         # remove everything

This install is for trying it out. Everything listens on 127.0.0.1 only, so nobody else on your network can reach it. For a real team, the same stack deploys to AWS with Terraform: a load balancer with TLS, private networking, managed Postgres and Redis, KMS for credentials, and Object Lock for the audit anchors.

What it does not do

Countersign limits what an agent can do. It does not try to detect prompt injection, and that was a deliberate choice. If an agent is tricked into asking for something dangerous, a person still has to approve it.

It only speaks to MCP servers over HTTP. Servers that only run locally over stdio are not supported yet.

And the source code is private for now. I have not decided how I want to release it. The install above uses the published images, so you can run it without the code.

What I learned

Local MCP was about giving an AI access to my machine. Countersign was about controlling that access for a team.

Most of the work was not the gateway itself. It was answering specific questions. Which agent does this token belong to? What does the agent do while a person decides? What stops one organisation from reading another's data if my code has a bug? How do you prove an audit log was not edited?

Each answer became a design decision, and most of those decisions have a test that tries to break them.

That is how I want to build anything that touches real systems from now on: decide what it should refuse, and test that it does.