Postbag MCP server

<!-- mcp-name: io.github.parasxos/postbag -->

postbag

Two agents, one bag of letters.

Let two existing Claude Code or Codex sessions review each other's work, split a task, or exchange a second opinion. They run on the same machine, receive letters through their native inboxes and share one recorded history.

pipx install 'postbag[mcp]'

Five MCP tools and a CLI. Postbag adds no delivery daemon, polling, hooks or remote relay. It carries text and records submitted letters. The agents and their hosts decide when to reply and when to stop. Code and other work products stay in your repository.

Real CLI commands with fake inboxes and a temporary home. This is a local demonstration, not a recording of live agents. Demo source.

See agent installation instructions.

Install

pipx install 'postbag[mcp]'
postbag --version
postbag-mcp --version

Python 3.10 or later, on macOS or Linux. Use pipx install postbag for the CLI alone, which uses only the standard library. Upgrade both peers' CLI and MCP installations together and reconnect their MCP servers. Existing bags need no migration. Once a bag contains a leave record, all its readers need 2.1 or later. See migration details.

Each vendor in use brings its own door. A Claude Code session exports CLAUDECODEMESSAGINGSOCKET and CLAUDECODEMESSAGINGTOKEN to the commands it runs. A Codex session exports CODEXTHREADID (older versions use CODEXSESSIONID) and has a codex binary with the queue command (0.149 or later). Set POSTBAG_CODEX if it is not in the ChatGPT app or on PATH. Two Claude sessions need no Codex binary, two Codex sessions no Claude socket.

MCP tools

The optional MCP interface lets agents call postbagjoin, postbagleave, postbagsend, postbagread, and postbag_bags directly. Sender identity comes from the host. The ledger and native delivery are the same as the CLI. Joining creates a missing bag. There is no letter budget or human-only command.

Install the optional tools with:

pipx install 'postbag[mcp]'

Or let uv run the pinned package in an isolated environment:

uvx --with 'postbag[mcp]==2.2.0' postbag@2.2.0 mcp

This starts a stdio MCP server for a host to manage. It waits for protocol input, rather than opening an interactive terminal prompt. postbag mcp and postbag-mcp serve the same five tools. The launcher takes no --bag or operational arguments. Each tool call selects its own bag.

Register the absolute path to postbag-mcp as a local stdio MCP server in each host. Setup, upgrades, and compatibility. The MCP SDK is required only for this interface.

Shortened. The full README is on GitHub.