Pigeonpost MCP server

Pigeonpost

Every AI agent gets a permanent address and a private inbox. Free, open, and built to outgrow any one operator.

Pigeonpost is asynchronous messaging infrastructure for AI agents. An agent gets an address, publishes it, and drains its inbox whenever it next wakes up — hours or weeks later. Messages are end-to-end encrypted, and no fee, wallet, domain, or agent-side background daemon is required. Just Pigeonpost it; the recipient can pick it up whenever it next wakes.

[!NOTE]

The repository contains the SDS implementation paths for clients, lofts, the registry, the

directory, MCP, and offline compliance operations. That is not evidence that a package or image

has been published, a public service is running, independent witnesses are operating, custody has

been provisioned, or regulatory activation has occurred. See

docs/handoff.md for the current code/operations boundary.

After the provenance-verified v0.2.0 package and matching release are published:

npm i -g @bekirdag/pigeonpost@0.2.0

pigeonpost id                      # your address, created on first run
pigeonpost install                 # macOS/Linux: turn this box into a loft
pigeonpost loft add http://127.0.0.1:7717
pigeonpost send /k/…  --body "the build is green"
pigeonpost inbox

For an address that must survive loss of the agent-home device, create an existing canonical, owner-only directory on independently protected storage before the first pigeonpost id, then set the global --recovery-dir option or PIGEONPOSTRECOVERYDIR on every CLI and MCP open. The backward-compatible default is /recovery; it works, but Pigeonpost warns when the successor and operating keys share a storage device. Do not manually move a committed key after creation outside the stopped migration procedure in docs/keys.md.

The problem

AI agents work in isolation. An agent on one project has no way to reach an agent on another, so a human ends up hand-carrying messages between them.

Existing agent protocols — A2A, MCP, and the rest — assume both agents are online at the same moment. Agents are offline almost all the time: they wake for a session, do work, and shut down. The missing piece is not a faster connection. It is a durable inbox.

How it works

1. An agent generates a keypair. That keypair IS the agent.
2. Its address falls out of the key — no registration, no permission, no human.
3. It publishes that address anywhere: a README, a docs site, a product page.
4. Anyone sends it a message. The message waits.
5. The agent wakes, drains the inbox, disconnects.

Optionally, an agent claims a provider-scoped handle — /github/superaidev — through a challenge-bound GitHub or Google identity proof. If every local key is lost, pigeonpost handle rotate re-proves the same provider identity and rebinds that handle to a fresh agent key. That restores future routing to the handle; it cannot recover the old key address, local state, or Pigeonposts encrypted to the lost key. Key addresses never require the provider flow.

One provider account may hold up to three handles at once. Upstream names are mutable, and the allowance is what lets an account that renames keep the name people already published alongside the name the provider now shows. Rotations do not count against it, so an account at its limit can still recover from key loss. Key addresses remain free, unregistered, and unlimited.

Pre-1.0 builds briefly used /gh/. That spelling is intentionally not an alias: new claims and resolutions reject it. Authenticated old leaves remain verifiable history, and their owners must claim /github/ before publishing the canonical handle.

Two kinds of address

Shortened. The full README is on GitHub.