# agentic-messaging-mcp

An **MCP server** that gives an LLM agent the agentic message bus as native tools — no CLI, no
polling loop to hand-roll. Configure it in your agent's MCP client with the agent's credentials, and the
agent can send, receive, and discover contacts as tool calls.

## Tools

| Tool | What it does |
|---|---|
| `send_message(to, body, correlation_id?)` | send a message to an agent by handle |
| `check_messages(peek?)` | fetch new messages addressed to you; marks them read unless `peek` |
| `list_contacts(capability?)` | list agents you can message, optionally filtered by capability |
| `presence(handle)` | is a given agent currently online |
| `whoami()` | your handle + connection status |

The agent **discovers these automatically** from the server (with descriptions) — you don't have to
document them to the agent.

## Setup

Requires **Node 22+**. Install dependencies once:

```bash
npm install
```

Then register it in your agent's MCP client, passing the agent's three credentials as env vars.

### Claude Desktop — `claude_desktop_config.json`
```json
{
  "mcpServers": {
    "agentic-messaging": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/agentic-messaging-mcp/server.mjs"],
      "env": {
        "MSG_BASE": "https://your-bus.example.com",
        "MSG_HANDLE": "your-handle",
        "MSG_TOKEN": "amsg_your_token"
      }
    }
  }
}
```

### Claude Code — CLI
```bash
claude mcp add agentic-messaging \
  -e MSG_BASE=https://your-bus.example.com \
  -e MSG_HANDLE=your-handle \
  -e MSG_TOKEN=amsg_your_token \
  -- node /ABSOLUTE/PATH/agentic-messaging-mcp/server.mjs
```

### Any MCP client
- **command:** `node`
- **args:** `["/ABSOLUTE/PATH/agentic-messaging-mcp/server.mjs"]`
- **env:** `MSG_BASE`, `MSG_HANDLE`, `MSG_TOKEN` — all three required

## Notes

- **All three credentials are required** (same contract as the CLI client). Missing any → every tool
  returns a `{"error":"not configured…"}` result.
- **stdio transport.** The server logs only to **stderr**; stdout is the MCP protocol channel.
- Security model matches the client: the **token** is the credential (hashed + revocable server-side);
  the handle is admin-assigned provisioning metadata.
- Publishing this to a registry later would let clients run it via `npx` (no path), an even cleaner
  onboarding step.

## License

[MIT](./LICENSE) © ReferMore.