Gage MCP server
Commit Nov 15, 2026Enables secure, signed handoffs between AI agents using a reading frame that prevents prompt injection and verifies sender identity.
Also known as warewithall2/gage
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.6
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is Gage MCP?
Gage enables secure, signed handoffs between AI agents using a reading frame that prevents prompt injection and verifies sender identity.
Summary generated from the project's README
About Gage MCP server
Securing handoffs between AI agents is what Gage enables by providing a signed, sealed directory for transferring files, prompts, and decisions. It addresses the risk of prompt injection by using a reading frame that informs a receiving agent that the incoming payload is strictly data without authority. This system is designed for developers and teams who need to move project states or tasks between different LLMs, such as Claude and Codex, without handing over implicit trust.
Users manage identity through a controlled allowlist and a human-in-the-loop ceremony where two people compare four word-pairs to confirm a key. The server operates locally or across a LAN using gage lan, and it can be integrated into an agentic workflow via the Model Context Protocol using the gage mcp command. Because bundles are signed directories, they can be moved through any existing channel like git, email, or shared folders. The system distinguishes between a valid signature and a confirmed identity, ensuring that unconfirmed senders are clearly labeled.
What you can do with it
- 1Secure agent-to-agent task handoffsAn AI agent can pass a complex task and its current state to another agent using a signed bundle.
- 2Preventing prompt injection during data transferA developer can ensure that incoming instructions from another agent are treated as data rather than commands.
- 3Verifying human-confirmed identitiesA user can record that they have manually verified a colleague's cryptographic key through a word-pair ceremony.
- 4Integrating secure communication into MCP clientsAn AI client can use the Model Context Protocol to drive the Gage handoff process directly.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablewarewithall2/gage is public and reachablegithub.com/warewithall2/gage ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-05github.com/warewithall2/gage ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubgage
Hand work between AI agents without handing over trust.
Your Claude hands a task to Codex. A colleague's agent sends you their project state. Normally nothing on the receiving end says who wrote it, or whether you have ever confirmed that person — and an agent reading its inbox is not a human reading email. A human who reads a phishing message is not executing it; an agent is. A channel that lets one LLM send prompts to another is, by default, a prompt-injection delivery network.
gage is that channel built the other way round. It is three things:
- A bundle — files, a prompt and decisions in a signed, sealed directory.
- A list you control. Two people compare four word-pairs over a channel
neither machine controls, and
gage confirmrecords that they did. A key nobody has confirmed still works and says so —SENDER ON YOUR LIST, UNCONFIRMED— because being on a list and having been checked are two different facts and only one of them is a claim about a person. Arrival is not consent either: a bundle that lands in your inbox sits there unread until you accept it. (A sealed file somebody hands you is the exception, and the frame says so when you open one: pointinggage openat a directory is itself the decision, and there is no gate behind it.) - A reading frame. Before any payload, the receiving agent is told that this is data from an identified party carrying no authority — and when the sender is not attributable under a key you currently accept, the contents are withheld rather than annotated, because an annotation is something the payload can argue with.

Every line of that recording is genuine output. The same capture is docs/demo.md as annotated text and docs/demo.cast in asciinema v2 format, and scripts/demo.sh reproduces it in a throwaway directory without touching your own gage home.
Try it:
curl -fsSL https://gage.sh/install.sh | sh # verifies its own checksum
gage quickstart
It works across vendors because it is not a protocol: a bundle is a signed
directory, so it moves over a shared folder, git, email, or anything else you
already have. There is a viewer (gage ui), machines find each other on a LAN
with no server in the middle (gage lan), and an agent can drive the whole
thing itself over MCP (gage mcp).

A gage is a pledge: something of value handed over to stand behind a promise, and historically the glove thrown down to open a challenge. Both senses fit. Everything downstream — every verdict, every grant, every unattended acceptance — rests on that one human moment.
"Why not just sign the payload yourself?"
Asked by a reviewer, and no document here answered it, which is a gap worth closing because it is the first question anyone technical will have. Ed25519 is forty lines away in any language. If you want a signed handoff, sign the tarball and send it.
What that gets you is authenticity. Every part of the gap between that and this is a local decision the signature cannot make for you:
- A signature says a key signed something. It does not say you ever agreed to hear from that key. The verdict is computed from your allowlist, and — since this release — from a record that a human compared four word-pairs with its owner. "Valid signature" and "someone I have confirmed" are different sentences, and only one of them is a statement about a person.
- Verifying it yourself means writing the verdict yourself, and the interesting verdicts are the ones nobody writes until they have been burned: a key you retired that is still signing; a bundle that cannot be placed either side of that retirement; a key you looked at and refused. Each needs local state the signature knows nothing about — an allowlist, a retirement cut, an observation counter — and getting the direction of each one wrong is the difference between a warning and a thief's content rendered as a colleague's.
- The payload still has to be read by a model, and that is the half this is really about. A verified payload is still someone else's prose arriving where your agent takes instructions. The frame, the fence nonce, the per-item kind labels, the withholding rules, the accept gate — none of that follows from a signature, and all of it is what decides whether a signed message becomes a prompt-injection delivery vehicle with a certificate.
- And the honest limit: the frame is text, and text does not outrank the
host prompt. See docs/dogfood-2026-10-15.md,
where that is what happened.
gage authorityexists because the only thing that can grant authority is the receiver, in a file no sender can reach.
So: sign the tarball if the question is "did this come from them". This is for the question after it, which is "and what may my agent do about it".
The receiving agent's half of the trust boundary
Signing what an agent does is well covered by other work — receipts over tool calls, verified at the server that executes them. See docs/prior-art.md. gage is the other end: what the agent reading a message is told about it, in the seconds before it decides what to do.
What it does NOT stop: docs/what-this-does-not-stop.md answers the 2026 agent-security incidents one at a time — Cursor's sandbox escape, the coding agents that leaked their own keys to a PR title, the Cline bot that shipped a backdoored release off a GitHub issue title — and the answer for every one of them is no, gage would not have prevented that. They arrived over the web, a pull request, an issue tracker, an email, a package registry. gage is one channel between two parties who confirmed each other's keys. The same file carries the MCP server audit and the one hole it found.
The wire reality and the limits: docs/spec.md is what is actually on disk and on the network — the bundle layout, what is signed, how a receiver computes trust, the relay protocol — derived from the code rather than from intent. docs/threat-model.md is the adversaries, the mitigation for each, and the non-goals: the things gage deliberately does not protect against, including the central one, that nothing here can make a language model obey the frame.
On A2A: docs/a2a.md says how this maps onto Google's Agent2Agent protocol, and what gage deliberately is not — not a transport, not a registry, not an identity provider. It is a design position, not code: gage speaks no A2A today.
Calling it from an agent: docs/mcp.md — gage mcp serves
the Model Context Protocol over stdio, so an agent calls gage as tools
(claude mcp add gage -- gage mcp). The word-pair ceremony survives the hop:
pairing needs the pairs echoed back, and the page is honest about what that
echo does and does not prove.
Driving it from a script: docs/agents.md is gage with no
human at the keyboard — the command table for a whole handoff, the exit codes
(checked, including the case where 1 rather than 2 means "could not read
it"), how to read a verdict out of the output, one complete worked script, and
the honest boundary: what an agent can and cannot do about confirming a key.
On losing your key: docs/adr-identity-recovery.md is the decision record for identity recovery — why encrypted export won, why trusted-contact recovery was rejected as a new social attack surface that fights the ceremony model, and the specification the implementation follows. The trade it commits to is stated plainly there and in the threat model: opting in converts "lose the key, lose everything" into "your security is your passphrase's strength".
That matters because the reader is different. A receipt's verdict is read by a program at an admission check, which cannot be talked out of its conclusion. A bundle's verdict is read by a language model whose next tokens are the payload itself, and which can. That difference is the whole reason the frame exists.
So gage open is a renderer, not an importer. It puts the bundle inside a frame
that states, before any payload, that the contents are data from an
identified party and carry no authority — and on a bad verdict it withholds
the contents rather than annotating them, because an annotation is something
the payload can argue with.
Three specific defences, each written after the attack worked in testing:
- Nonced fence markers. Payload text containing
=== END RECEIVED CONTEXT ===would otherwise close the frame, and everything after it reads as the tool's own trustworthy voice. The real markers carry a per-invocation random nonce the sender cannot predict. - Keys are identity; handles are claims. An early version printed
sender: alicebeside a verified-trust label while the key belonged to bob. Your own name for a key now leads, and a mismatch is stated loudly. - Trust is computed, never carried. There is no trust field in the
manifest. The receiver derives it from the signature and its own allowlist,
because a
"trust": "verified"key in a document the sender controls is decorative.
Payload digests are checked against the signed manifest, so a signed manifest beside swapped files is caught and the contents are withheld.
Which verdicts withhold, exactly. This is worth stating plainly, because
an earlier version of this README said "on a bad verdict" and left a reader to
guess the set — and the guess most people make is wrong. Contents are withheld
on a digest mismatch, and for SENDER UNVERIFIABLE, SENDER KEY REJECTED and
ARRIVAL UNRECORDED: the cases where nothing can be pinned on anybody.
Contents are shown, with the verdict above them, for SENDER NOT ON YOUR LIST, SENDER REFUSED BEFORE and SENDER ON YOUR LIST, UNCONFIRMED. Those
are attributable — a real signature by a real key — and withholding them would
make the ordinary first contact with a new person unusable while buying
nothing: whoever handed you the file can hand you the file again. What you
get instead is the verdict, before the payload, every time.
Freshness and run are verdict facts too. A bundle may carry a sender-set
expiry (--ttl / --expires) and a declared context (--context) naming
the run it belongs to. An expired bundle joins the withheld set above; it
stays in the inbox, listed and marked, because arrival is not acceptance.
Where this machine knows its own run context (GAGE_CONTEXT, or the first
line of <home>/context), the verdict also states the comparison -- match,
mismatch, undeclared, no-local-context -- next to the signature, in the
frame, the inbox, the viewer and the JSON. A match authorises nothing; it
rules out one specific mistake, yesterday's handoff read as today's. The
exact semantics are in docs/spec.md; the limits are in
docs/what-this-does-not-stop.md.
Keys, said out loud
$ gage whoami
owen yomSmC3TalJ5IM+H0yvkhhWVab4ujiAVIQFR4WvdXiM=.KlXt+/5rj4y3FMC7eqau4zF5eZV+x7PjYZUdyUXHDEM=
this key says : carved daffodil · grand lintel · spiced barley · bright iguana
device label : humble pillar (from the signing key alone, so NOT the first
pair above -- it is how others tell machines apart)
LocalSend labels a device with a word pair and it is the nicest thing about
using it — but there the words are a name the device picked, so anyone can
be Yellow Iguana. Here they are derived from the signing key, so nobody
chooses their own and two machines showing the same words are holding the same
key. gage fingerprint <name> says a contact's, and gage add prints the words
for the key it just took, which is the moment you confirm it with them over
some other channel.
Two lengths, because one cannot do both jobs. A single pair is 16 bits: lovely, and useless as a check, since an attacker generates keypairs until theirs also renders "humble pillar" — about 65,000 tries. So the pair is a label, for telling devices apart in a list, and nothing is ever confirmed against it. The fingerprint is four pairs, 64 bits, and is what a person compares.
They come from the same function, so for a key with no encryption half the label is the fingerprint's first pair. For the key above it is not — look at the two lines again. The fingerprint covers the signing key and the encryption key, because confirming only the signing half let an attacker substitute the key your mail gets sealed to and still pass the comparison word for word. The label covers the signing key alone, and has to: a bundle's manifest carries nothing else, so that is the only nickname a receiver can derive for a sender it has never met.
This paragraph used to say the label was "always a real prefix of the
fingerprint", spec.md and words.rs agreed, and the example above was
written to match — which is how a wrong claim survives three documents. It was
wrong for every contact you can seal to. A unit test now fails if the two ever
line up again.
The second machine
Install it, then one command on each:
$ gage lan
new identity, named after its own key: grey crowbar
grey crowbar · lavish jackdaw · sleepy hedgerow · electric delta
gage lan -- you are "grey crowbar" on this network
visible and reachable while this runs, silent the moment you stop it
anything sent to you lands unread in inbox/pending
broadcasting to: 255.255.255.255, 192.168.1.255
gallant alcove at 192.168.1.44:7791 (not paired)
says : gallant alcove · indigo burrow · merry banner · glassy nettle
Then send, by the two words on the list:
$ gage send --to "gallant alcove" --subject hi --file notes.md --lan
handed to gallant alcove at 192.168.1.44:7791, over this network
it is in their inbox/pending -- not accepted
No name to choose, no key to copy, no pairing first, no relay. The name is two words taken from the signing key, so nobody picks their own — LocalSend's device names, except derived rather than chosen, which makes them a slightly better label at no cost to the person.
Presence is the process. It announces while gage lan is in the
foreground and goes silent the moment you stop it. That is LocalSend's own
answer to the same objection, and a better one than the flag this started
with: the state is visible on screen rather than sitting in a number of
seconds you have to remember you passed.
Pairing is an upgrade, not a gate. An unpaired machine can send to you
and what arrives is SENDER NOT ON YOUR LIST, unread, behind the same accept
gate as everything else — which is the protection, and always was. When you
want a key confirmed rather than merely observed:
$ gage pair laptop
gallant alcove at 192.168.1.44
says : gallant alcove · indigo burrow · merry banner · glassy nettle
Does the other machine show EXACTLY those words? [y/N] y
Four word-pairs is 64 bits and is what a person compares; the single pair in the list is 16 bits and is a label only, never confirmed against, because grinding 65,000 keypairs to match one is trivial. That confirmation is what makes a key yours rather than some machine on this wifi, which is what a grant should require before an agent acts on a message unattended. Requiring it before one file could move was a step I added and it was wrong.
Underneath, gage nearby, gage pair and gage listen are still there as the
explicit forms, and gage listen is the one to use for a machine that should
be reachable without announcing — it answers an address query only when the
query is signed by a key already on your list, so a stranger gets silence they
cannot tell from an empty network. Design and the costs:
docs/lan-discovery-design.md.
Authority: the one thing that says you may act
Everything above is about what is known. None of it says whether an agent may do what a message asks — and it cannot, because a bundle cannot authorise its own fulfilment, however well signed. That gap is real and was measured: dogfooding this across four agents had two of them read a verified request from a verified contact and decline, correctly, for want of authority.
So authority is computed by the receiver from its own list, exactly as trust
is. ~/.gage/authority is a file your human writes:
# no gage command writes this file; edit it yourself
allow codex review-request
allow dana question in-reply-only
allow <a-public-key> any # any message KIND, not any action
gage authority prints what is granted. There is deliberately no command
that writes a grant — a gage allow would be reachable by prompt injection,
letting an agent talked into running it grant itself permission to obey
whatever talked it into it. Edit the file yourself.
That guard is a deterrent, not a boundary, and the frame now says so. Any
process that can read this file can also write it, so an agent with a shell
can add its own grant — which is exactly how the grants for the 15 October
reviews got written. Removing the documented command means an injected agent
has to be told to hand-write a file, which is conspicuous in a transcript; it
does not make the file unwritable. A real boundary needs file permissions or
a separate process the agent cannot write through. open therefore tells the
reader never to edit the file, or add a grant, because a message asked it to.
Three rules, in the order they would hurt to get wrong:
- A grant only ever follows
SENDER VERIFIED. Any other verdict and no grant is consulted at all. A grant that followed a forged or stolen key would be worse than having no feature. - A malformed file grants nothing. One unusable line voids the whole file, because the other direction lets a typo on line 2 widen line 3 — and the failure directions are not symmetric. Too little authority asks a human a question; too much acts on a stranger's instruction.
- A grant is for a kind of message, and the frame names the one act it
permits. The scope comes from the kind, in
MsgType::granted_scope— areview-requestpermits reading what the bundle encloses and reporting findings, and nothing else. The first version said "you may act on what this message asks, within what it asks", which handed the boundary to the payload; both reviewers caught it independently. Editing files, running commands, committing, pushing, sending anything, messaging a third party and touching secrets or keys are listed as never covered, whatever the payload asks. - The grant line carries the frame's nonce, so a payload cannot write a complete one. That raises the bar against a copied static string. It does not make a positive grant unimitable, because the reader is a model that can be argued into ignoring a marker, and the frame says as much rather than leaning on it.
No expiry yet, on purpose — it cannot use a clock, for the same reason key retirement cannot, and "expires after N observed messages" is a strange thing to ask a person to write. A file you edit is already revocable by editing it.
Gage MCP questions
How does gage prevent prompt injection?
It uses a reading frame with nonced fence markers that the sender cannot predict, ensuring the payload cannot prematurely close the frame and masquerade as the host.
Can I use gage with my existing AI agents via MCP?
Yes, gage provides an MCP server that allows agents to call gage as tools.
Does gage verify if a signature is valid or if I trust the person?
It does both, but distinguishes between them; a valid signature only proves authenticity, while gage computes a trust verdict based on your local allowlist and human confirmation.
What happens if a sender is not on my allowlist?
The contents are still shown but with a verdict displayed above them, allowing for first contact with new people without being vulnerable to unverified authority.
Is gage a transport protocol?
No, it is not a transport or a registry; it uses signed directories that can move over any shared folder, git, or email.