# agent-comm [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/keshrath/agent-comm  
**GitHub Stars:** 9  
**npm Downloads (last month):** 945  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agent-comm

## Description
Agent intercommunication - messaging, channels, shared state, and real-time events

## Tools
Capabilities this server exposes over MCP:

- **comm_register** — Register with name, capabilities, metadata, skills, and auto-join channels
- **comm_agents** — Agent management — actions: `list`, `discover`, `whoami`, `heartbeat`, `status`, `unregister
- **comm_send** — Send messages — direct (`to`), channel, broadcast, reply (`reply_to`), forward (`forward`)
- **comm_inbox** — Read inbox (direct + channel messages, unread filter, `importance` filter, thread view via `thread_id`)
- **comm_poll** — Block until a new inbox message arrives (supports `timeout_ms` and `importance` filter)
- **comm_channel** — Channel management — actions: `create`, `list`, `join`, `leave`, `archive`, `update`, `members`, `history
- **comm_state** — Shared key-value state — actions: `set`, `get`, `list`, `delete`, `cas

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agent-comm": {
    "command": "npx",
    "args": ["agent-comm"]
  }
}
```

## Documentation

## What agent-comm MCP server does

The agent-comm MCP server provides a shared coordination service for multiple AI agents working concurrently. Each agent can register an identity with capabilities, metadata, and skills, then discover other registered agents by capability or tag. Registration can also include channels to join automatically.

Communication supports direct recipients, channels, broadcasts, replies, and forwarded messages. Messages can carry importance levels from low through urgent, and inbox queries can filter by unread state or importance. Thread views use a thread identifier to collect related messages.

The service also supplies a shared key-value store. Agents can set, retrieve, list, and delete values, or use compare-and-set for atomic updates. This supports coordination data such as locks, flags, and progress markers without requiring every agent to maintain a separate copy.

## How it works

The agent-comm MCP server runs as one Node.js process and exposes MCP over standard input and output for AI hosts. The same process can provide REST endpoints and WebSocket events for scripts, hooks, and the web dashboard. Its persistent data is stored in SQLite using WAL mode, allowing multiple connected hosts to work with the same agents, messages, channels, and state.

The seven MCP tools group the main operations by concern:

- `comm_register` creates an agent identity and optionally joins channels.
- `comm_agents` lists, discovers, identifies, heartbeats, checks, or unregisters agents.
- `comm_send` delivers direct, channel, broadcast, reply, or forwarded messages.
- `comm_inbox` reads messages, including filtered and threaded views.
- `comm_poll` waits for a new inbox message, with timeout and importance filters.
- `comm_channel` manages channel membership, metadata, archiving, and history.
- `comm_state` manages shared values, including atomic CAS updates.

A browser dashboard is available at the local server address and presents agents, messages, channels, shared-state entries, and activity in real time. The project also includes optional hooks that use REST calls to coordinate file edits and guard selected shell operations; those hooks are separate from the MCP tool calls.

## Setup and configuration

Install the published package globally with `npm install -g agent-comm`, then add a stdio MCP entry that runs `npx agent-comm`. A generic configuration uses `agent-comm` as the server name, `npx` as the command, and `agent-comm` as its argument. The dashboard starts at `http://localhost:3421` after the first MCP connection.

For a source installation, clone the repository, install dependencies, and run the build. The standalone process can be started with `node dist/server.js --port 3421` for REST or WebSocket clients. The repository also provides `npm run setup` for Claude Code; this registers the MCP server, installs the supplied hooks, and configures permissions.

Host configuration paths vary. Cursor is identified as read-only for state in the tested-host list. Hosts need MCP support for the stdio option, while custom clients can use HTTP interfaces.

## Limitations and notes

The server requires Node.js 20.11 or newer. MCP access uses stdio, while REST and WebSocket access is intended for standalone clients, hooks, dashboards, or custom scripts. The supplied coordination hooks can block conflicting edits or selected commands, but they must be installed separately; the MCP primitives alone do not enforce that an agent follows a coordination procedure.

The file-coordination behavior depends on the REST service being available on the configured local port. Review those recipes before relying on hooks in a particular development environment.

_Full upstream README: https://allmcps.com/mcp/agent-comm/readme_