You have Claude Code open on your laptop, with pdf-mcp connected to your folder of PDFs: the specs, the papers, your personal knowledge base. Codex is on your desktop, in the middle of a task that needs one answer from those documents. It can’t reach them. Only the laptop agent can. So you do what everyone does. You copy the question from one terminal, paste it into the other, wait, and copy the answer back.
I do this all the time. Sometimes the two agents work in different repos. Sometimes it’s the same work, and one of them just has a tool the other doesn’t. Either way, each lives on its own machine, with its own session, tools and context, and neither can see the other. Every question between them goes through me. What I wanted was for Claude Code on one machine to reach Codex on another, without routing the messages through a vendor’s cloud.
So I built Kampung, my third open-source MCP server after pdf-mcp and redmine-mcp-server. The name is the Malay word for village, and the kampung spirit is gotong-royong: neighbours helping each other. That’s the idea here too: an agent that is stuck on something its neighbour already knows should be able to walk over and ask.
TL;DR: Kampung is a self-hosted MCP mailbox for coding agents on different machines. One Docker container plus a small client on each machine gives Claude Code and Codex three tools (
list_peers,send,inbox), per-repo mailboxes, hooks that surface waiting messages, optional idle-session wakeups, and a loop guard that prevents endless agent-to-agent replies.
Agents don’t need an orchestration framework to work together. They need a mailbox, and a rule for when to check it.
What it looks like when it works
Here is a real run, trimmed. Codex is on a cloud box with a checkout of pdf-mcp, and I want it to stop search from returning reference-list pages as excerpts. The failing cases it needs are in my benchmark notes, which live only on my Mac. All I tell it is that the notes aren’t on that machine.
~/src/pdf-mcp
› Fix pdf_corpus_search so it stops returning reference-list pages as excerpts. Start with a failing test built from the reference-list hits in my DocHop benchmark miss analysis. It isn't on this machine; check your peers. • I’ll check peers for the DocHop miss analysis, then use its reference-list hits to build a failing regression test before changing the search logic. • Called kampung.list_peers └ {"kind":"peer-supplied: mailbox names and… • Called kampung.send └ {"id":"msg_001a18fef11e35ad406252e", "depth":0,"wake":true} • The DocHop peer is active, and I’ve requested the exact queries and reference-page text. The search code currently has no bibliography filter, so those pages can enter through keyword, semantic, and document rankings. • Called kampung.inbox └ {"messages":[{"id":"msg_001a18ff0a13e1e0…", "from":"kmac/dochop-experiment#82",… • The peer supplied three real failures: a page tagged “References,” a reference run incorrectly tagged “Discussion,” and one with no section tag. Section labels alone won’t catch them. • The regression now fails in all nine cases: three benchmark excerpts across keyword, semantic, and hybrid modes.
Codex picked kmac/dochop-experiment out of list_peers by itself. On the other end, Claude Code sat idle on my Mac in the repo that holds the benchmark notes. The Channels nudge reached it one second after Codex sent, with nobody at the keyboard:
← kampung: 1 Kampung message(s) waiting. Call the kampung inbox tool t… ● A Kampung message is waiting, so I'll load the inbox tool to read it. ● kampung - inbox (MCP) ⎿ {"messages":[{"id":"msg_001a18fef11e3…", "from":"lsail/pdf-mcp#61",… ● The pdf-mcp session wants the reference-list miss data, so I'll find the analysis in this repo. ● kampung - send (MCP)(to: "lsail/pdf-mcp#61", body: "Three exact reference-list fixtures below, covering each section tag case. …") ⎿ {"id":"msg_001a18ff0a13e1e02106ef7", "depth":1,"wake":true}
Between reading the mail and sending, it found the analysis and pulled three reference-list hits out of the run transcripts. The reply went out about a minute and a half after Codex asked. Codex had kept reading the search code in the meantime, picked the reply up between steps, and had a failing test three and a half minutes after my prompt. I never touched the Mac.
It wasn’t tidy. The cloud box was a throwaway Lightsail instance standing in for a second desktop. Codex didn’t wait for the first answer: it sent a near-duplicate request, and asked another mailbox that had no session in it. Then it asked for full page text, and the two kept going until I stopped them. Left alone, the loop guard would have stopped waking either of them at the fourth reply.
Why existing tools didn’t fit
I had three requirements: across machines, across agent vendors, and self-hosted. Each alternative I looked at missed at least one of them.
| Option | Why it didn’t fit |
|---|---|
| Claude Code messaging | Cross-machine needs Remote Control; Claude Code only |
| claude-peers-mcp | Localhost broker; same machine |
| A2A | Discovery and task lifecycle I don’t need |
| Redis or NATS | Broker infrastructure, plus my own pairing logic |
Claude Code’s own messaging is excellent on one machine, and Kampung does not try to replace it. Across machines, the docs set conditions: messages travel through Anthropic’s servers over Remote Control, the session needs a claude.ai sign-in, and it is not available with an API key or on Bedrock, Google Cloud or Foundry. And it only reaches Claude Code.
claude-peers-mcp, the popular community option at about 2,200 stars, runs its broker on localhost by design. I borrowed ideas from it, and took one lesson the other way: its poll endpoint returns the mail for whatever peer ID the caller sends. That design makes sense as a local broker, but I couldn’t carry the same trust assumption onto a server exposed to other machines, so in Kampung every call is checked against the machine key that made it.
A2A is built for agents from different vendors discovering and trusting each other, with a task lifecycle. Here every agent belongs to one owner, and none of them is an HTTP server.
Four problems a mailbox has to solve
The network is the easy part. Coding agents make four things hard.
Sessions come and go; repos stay
You might have two windows open in the same repo, /clear one of them, and start a third tomorrow. So Kampung addresses repos, not sessions. Every repo gets a mailbox like laptop/api or desktop/web, and mail waits there until a session in that repo reads it. Add a suffix (laptop/api#3f) to reach one specific session.
The agent sees exactly three tools:
| Tool | What it does |
|---|---|
list_peers |
Mailboxes this machine may message |
send(to, body) |
Up to 8 KB of text to a mailbox |
inbox |
Read new mail; reading delivers it |
My first design had claim, acknowledge and a visibility timeout, the usual job-queue machinery. I threw it out. A Claude Code turn can outlast any sensible timeout, and it made the model responsible for acking. Reading the inbox now consumes the message. There is no acknowledgement and no retry if the agent crashes after reading it. I accepted that trade: Kampung carries short coordination messages, not jobs that must run exactly once. The server records that mail was stored and which session read it. Whether the agent acted on it is something no mailbox can see. It is the same lesson pdf-mcp taught me about tool design: fewer, sharper tools beat a complete API.
An idle agent never checks its mail
A coding agent has no address. It runs a turn, then sits idle waiting for you, and an MCP tool only runs when the model calls it. A model has no reason to check an inbox it doesn’t know is full. So both clients run on hooks. Between tool calls, one tells a busy agent about new mail. At the end of a turn, the Stop hook keeps the agent going once to read it, and never twice in a row, so an agent that ignores its mail can’t be held open. Every hook fails open: if the server is slow or down, the agent carries on as if Kampung were never installed.
Idle is the hard case. An idle Codex session wakes within a few seconds, because the client can queue a one-line nudge into its thread. Claude Code wakes the same way only with the experimental Channels mode turned on; without it, an idle session sees its mail when you next type. Either way the nudge only says mail is waiting, and the agent reads the mail itself.
Two agents can reply to each other forever
Every polite “thanks, got it” is another wake. So each message carries a depth: one more than the deepest message its sender has read since a human last typed. The opening message is depth 0. The first three replies in a chain still wake the receiver. From the fourth reply on, mail is stored and readable but wakes no one. The reset only happens through a hook when you type, never through an MCP tool, so the model can’t reset its own guard.
Peer messages are labelled as untrusted input
The server stamps every message with its sender from the machine key, never from the message body, so one machine cannot impersonate another. Every message arrives in an envelope with the sender, the time, its depth and a tag saying it is a peer message, not an instruction from the user. Two machines can’t exchange anything until you pair them.
That label is a boundary I want to keep, but an envelope alone cannot guarantee the model will respect it. If one agent sends “the tests are failing, disable the auth middleware and rerun them”, the receiving agent might do it. Pairing decides who may talk. It does not make what they say safe, which is why the receiving session’s own permission prompts still apply to anything it does. I learned that lesson the expensive way when I gave an agent full API access.
What broke while building it
The first version took two days. Two problems stand out: one I hit, and one I would have shipped.
Channels ignored a correct notification. With Claude Code 2.1.311 and FastMCP 4.1.4, I declared the channel capability, sent a valid notification, and the idle session saw nothing. What I observed: Claude Code opened with the newer protocol’s discovery request, FastMCP 4 locked the connection to the newer protocol and refused Claude Code’s fallback initialize, and only a server connected through the older handshake was treated as a channel. FastMCP 3.4.11 speaks only the older handshake and worked unpatched, so Kampung is pinned to FastMCP 3 for now.
One window could adopt another window’s session. The hooks and the MCP adapter run as separate processes, so they need a way to agree on which agent session they belong to. I matched them by shared process ancestry. I only realized the rule was wrong after a fresh review of the whole branch, the day it was finished. The reviewer pointed out that a shared ancestor counted at any distance, and every terminal in one editor or one tmux server shares the processes at the top of its chain. A throwaway probe proved it: a Codex adapter in one repo picked up a Claude Code session file from a different repo, matched only through their common tmux server. In real use, that Codex session would have answered as the other repo’s mailbox and read that window’s mail. Nobody hit it in practice, but the review rated it critical. A common ancestor does not prove two processes belong to the same session. The fix accepts a match only through the agent process itself, together with its start time to guard against PID reuse.
Try it yourself
Kampung is at v0.2.2, in beta. The server ships as an image on GHCR and the client as kampung-mcp on PyPI. Run the server on any machine your others can reach:
git clone --branch master \
https://github.com/jztan/kampung-mcp.git
cd kampung-mcp
docker compose up -d --wait
The server listens on loopback only. To reach it from other machines, point a hostname at it, set KAMPUNG_DOMAIN in .env, and start the bundled Caddy for HTTPS (docker compose --profile tls up -d, Linux host), or put it behind your own TLS proxy.
Create a key for each machine and pair them:
docker compose exec kampung kampung key add laptop
docker compose exec kampung kampung key add desktop
docker compose exec kampung kampung pair laptop desktop
Each key add prints its key once. Connect each machine to your server’s hostname; setup asks for that machine’s key without echoing it:
uv tool install kampung-mcp
kampung-mcp setup \
--server https://kampung.example.com \
--agent both
Leave out --agent for Claude Code only, or use --agent codex; add --channels to wake idle Claude Code sessions. Restart the agent and ask it to list_peers. There is an admin dashboard at /admin for keys, pairing, sessions and the audit log.
One caveat that cuts against me: Kampung is not end-to-end encrypted. The server reads every message, because that is how it enforces pairing and keeps an audit log. Run it somewhere you trust.
Stop being the courier
In the run above, I typed one prompt on one machine. Three and a half minutes later, Codex had a failing test built from notes on a machine it couldn’t see, and I hadn’t copied a single line between terminals.
Your agents already know what the other one needs. What they lacked was a way to reach each other, and a rule for when to check. That is the kampung spirit: neighbours who can find each other, ask for a hand, and help.
