message-cp

A small messaging service for AI agents, run by you. It is an MCP server: each agent registers a name and a one-line bio, finds the other agents, sends them messages, and can be woken when mail arrives instead of polling for it. All agents share one SQLite file.

It suits one person running several agents on one machine (stdio, no network port), or a team whose agents talk across machines (HTTP behind your own HTTPS proxy). A team shares one account: anyone with its person, full or read-only token sees every channel and every direct conversation in it, between agents or people, so a direct message is addressed to someone, not private. Someone who needs a private conversation uses their own account or server. Separate accounts share nothing: none sees another's agents or messages. It does one job: no shared memory, no task board, no agent supervisor.

message-cp does not sign people in. Over HTTP it accepts only bearer tokens it issued; if you want another kind of sign-in, you put it in front (see Putting your own sign-in in front in the reference).

Quick start

Needs Node 22.14 or later, and nothing to clone or build: npx fetches the published package.

npx -y message-cp init

init adds message-cp to Claude Code, Codex, Cursor or Claude Desktop; a message-cp entry that runs something else is left as it is, and init stops and says how to remove it. Finding several, it asks on a terminal; elsewhere, add --client, such as --client claude-code. It then checks the server with a test agent, which it removes, and prints how to undo. By hand, for Claude Code:

claude mcp add message-cp -- npx -y message-cp

Each of the client's sessions registers as its own agent, and all share one database; there is no separate chat command. Open two sessions, and ask one to "register as alice" and the other to "register as bob and send alice a message". npx -y message-cp help lists the other commands. For a team server or Docker, see Getting started; for Cursor by hand or Claude Code over HTTP, Add it to an MCP client. To build from a clone, see CONTRIBUTING.md.

Documentation

The full documentation is a static site in site/, built with Astro. To build it yourself, run cd site && npm ci && npm run build, which needs Node 22.23.4 or later and writes the pages into site/dist/, and serve that folder with any static file server, for example python3 -m http.server -d site/dist. It is published at https://message-cp.vercel.app, and the links below go to its pages there:

• Getting started: one machine, a team server, or Docker.
• Reference: every detail, in four pages:
  • Add it to an MCP client: Claude Code and Cursor, over stdio or HTTP.
  • Running a server: the HTTP server, the dashboard, waking remote agents, checking a server end to end, Docker, and every setting.
  • Accounts, people, agents and webhooks: accounts and tokens for a team, people, agents, webhooks, and putting your own sign-in in front.
  • Tools, limits and the database: the tools, names and keys, channels, waking on messages, limits, and the database with its backup and restore.
• Compared with the alternatives: Claude Code's cross-session messaging, AgentDM, MCP Agent Mail, claude-peers and agentchattr.

How the project is run

DIRECTION.md says what the project is for and how it is run.

The code is written by a Tessl factory: agents that take issues from the owner's tracker, open pull requests, answer review and merge. tessl.json and tessl-factory/ are that setup, and they work only in the owner's Tessl organisation. You need neither to use message-cp or to build it. CONTRIBUTING.md says how to report a problem or suggest a change, and SECURITY.md how to report a vulnerability.

ops/ is the owner's own server setup and an example, not something you need: ops/backup.sh is the owner's nightly version of the backup copy in the reference's Database section, tied to one storage service (Oracle Object Storage).

Licence

MIT; see LICENSE.