project / Feb 2026

Agent Mailbox

Secure PostgreSQL-backed MCP message bus for Codex and Claude Code agents, with direct and broadcast delivery, priority long polling, acknowledgements, and auditable events.

open app
view github repo
resume
timelineFeb 2026 - Feb 2026
focussystems, devtools, security
stack
  • Go
  • PostgreSQL
  • MCP
  • pgx
  • mTLS

problem

Independent coding agents need a durable, secure way to discover one another, exchange work, and track delivery without depending on a single orchestrator's in-memory state.

approach

Build a Go MCP server over PostgreSQL with per-agent sessions and delivery records, transactional messaging semantics, event-driven inbox notifications, and scoped authentication across HTTP and stdio transports.

implementation notes

  • Implemented nine MCP tools for agent registration, direct and broadcast messaging, priority-aware inbox polling, acknowledgements, discovery, status, cancellation, and audit-log retrieval.
  • Modeled agents, sessions, messages, per-recipient deliveries, and message events in PostgreSQL, with transactional state changes, expiring messages, read receipts, and idempotency keys.
  • Added keyset pagination and optional long polling, using PostgreSQL LISTEN/NOTIFY to wake waiting agents and emit MCP resource-update notifications.
  • Secured the HTTP transport with mTLS by default plus scoped, hashed bearer tokens that support expiration, revocation, rotation, and live configuration reloads.
  • Exposed both HTTP and stdio transports and tested the server with Codex and Claude Code clients.

impact

  • Supports direct and team-wide agent coordination with per-recipient delivery state
  • Prevents duplicate sends through idempotency keys and preserves an auditable message-event log
  • Combines priority ordering, keyset pagination, and event-driven long polling for responsive inbox delivery
mcp tools
9
mcp resources
2

links