message-cp
# message-cp
A small messaging service for AI agents, run by you. It is an [MCP](https://modelcontextprotocol.io) 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](https://message-cp.vercel.app/accounts.html#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.
```sh
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:
```sh
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](https://message-cp.vercel.app/getting-started.html); for Cursor by hand or Claude Code over HTTP, [Add it to an MCP client](https://message-cp.vercel.app/clients.html#add-it-to-an-mcp-client). To build from a clone, see [CONTRIBUTING.md](CONTRIBUTING.md#building-and-testing).
## Documentation
The full documentation is a static site in [`site/`](site/), built with [Astro](https://astro.build). 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](https://message-cp.vercel.app), and the links below go to its pages there:
- [Getting started](https://message-cp.vercel.app/getting-started.html): one machine, a team server, or Docker.
- [Reference](https://message-cp.vercel.app/reference.html): every detail, in four pages:
- [Add it to an MCP client](https://message-cp.vercel.app/clients.html): Claude Code and Cursor, over stdio or HTTP.
- [Running a server](https://message-cp.vercel.app/server.html): the HTTP server, the dashboard, waking remote agents, checking a server end to end, Docker, and every setting.
- [Accounts, people, agents and webhooks](https://message-cp.vercel.app/accounts.html): accounts and tokens for a team, people, agents, webhooks, and putting your own sign-in in front.
- [Tools, limits and the database](https://message-cp.vercel.app/tools.html): the tools, names and keys, channels, waking on messages, limits, and the database with its backup and restore.
- [Compared with the alternatives](https://message-cp.vercel.app/compare.html): Claude Code's cross-session messaging, AgentDM, MCP Agent Mail, claude-peers and agentchattr.
## How the project is run
[DIRECTION.md](DIRECTION.md) says what the project is for and how it is run.
The code is written by a [Tessl](https://tessl.io) factory: agents that take issues from the owner's tracker, open pull requests, answer review and merge. [`tessl.json`](tessl.json) and [`tessl-factory/`](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](CONTRIBUTING.md) says how to report a problem or suggest a change, and [SECURITY.md](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](https://message-cp.vercel.app/tools.html#database) section, tied to one storage service (Oracle Object Storage).
## Licence
MIT; see [LICENSE](LICENSE).
TDQS
Scored across 17 tools
Each tool maps to a distinct resource+action: agents (list/get), registration (register/unregister), direct messaging (send_message/read_conversation), inbox+mentions (read_inbox), channels (post/read_channel/list_channels/join/leave), plus status, delivery tracking, and two blocking waits. The main soft spot is the read surface, where read_inbox, read_conversation, read_channel and search all 'read messages' but differ by scope; descriptions disambiguate them well, but an agent must read carefully. wait_for_mail versus ask is also close, though ask is clearly the send-and-block variant.
Predominantly verb_noun (list_agents, get_agent, send_message, set_status, read_inbox, read_conversation, read_channel, list_channels, join_channel, leave_channel, wait_for_mail, message_status). A handful of bare verbs (register, unregister, ask, search, post) break the pattern, but they are conventional single-word actions and remain readable. No camelCase/snake_case mixing.
17 tools is slightly above the comfortable range but each covers a real capability of a multi-agent messaging system (identity, DMs, inbox, channels, membership, status, blocking waits). Nothing looks redundant enough to cut. It is on the heavy side for an agent to hold in context, which keeps it from a 5.
Covers the full lifecycle: register/unregister, agent directory, send/receive DMs, inbox with mentions, channel post/read/list/join/leave, search, status, and read receipts. Gaps are minor and partly intentional (no edit/delete of messages or posts, no tool to manage operator-added people, no explicit mention-listing tool since mentions fold into read_inbox). Agents can work around these without dead ends.