@omnistreams/mcp-server

A Model Context Protocol server that bridges the OmniStream REST API to MCP clients such as Claude Desktop, Claude Code and Cursor. It lets an AI assistant read your inbox and send messages on your behalf through natural language.

Tools

| Tool | Description | Endpoint | |---|---|---| | list_conversations | List conversations (filter by status / assigned agent, paginated) | GET /api/conversations | | get_conversation | Fetch one conversation by UUID | GET /api/conversations/{id} | | list_messages | List messages in a conversation (cursor paginated) | GET /api/conversations/{id}/messages | | send_message | Send an outbound message (text or rich content) | POST /api/conversations/{id}/messages | | list_contacts | List / search contacts (by name, phone, email, tag) | GET /api/contacts | | search_messages | Full-text search across messages | GET /api/messages/search | | list_templates | List WhatsApp templates (filter by status / category / WABA) | GET /api/wa-templates |

All read tools are marked read-only. send_message is the only mutating tool.

Setup

1. Create an API key

In OmniStream, go to Developer → API Keys and create a REST key (requires the developer.access permission). Copy the key — it is shown once.

Tip: lock the key to your server's IP using the key's Allowed IPs field so a leaked key cannot be used from anywhere else.

2. Configure the server

The server is configured entirely through environment variables:

| Variable | Required | Default | Description | |---|---|---|---| | OMNISTREAM_API_KEY | ✅ | — | REST API key (os_..._...) | | OMNISTREAM_BASE_URL | | http://localhost:3000 | API gateway base URL | | OMNISTREAM_TIMEOUT_MS | | 30000 | Per-request timeout (ms) |

3. Add it to your MCP client

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "omnistream": {
      "command": "npx",
      "args": ["-y", "@omnistreams/mcp-server"],
      "env": {
        "OMNISTREAM_API_KEY": "os_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "OMNISTREAM_BASE_URL": "https://your-omnistream-host"
      }
    }
  }
}

Once configured, ask your assistant things like "list my open WhatsApp conversations" or "reply to conversation <id> with 'On my way!'".

Local development

npm install
npm run dev        # run from source over stdio
npm run build      # compile to dist/
npm test           # unit tests (vitest)
npm run typecheck  # type-check only

Security notes

• The API key is sent as the X-API-Key header on every request; it is never logged. Diagnostic output goes to stderr so it cannot corrupt the MCP JSON-RPC stream on stdout.
• Requests inherit the RBAC of the key's owning agent — the server cannot do anything the agent could not do in the UI.
• Combine with the API key IP allow list for defense in depth.