MCP Server#

Outeract ships an official Model Context Protocol server, so Claude, Cursor, and custom agents can send messages and read conversations with zero glue code. It exposes a curated subset of the Developer GraphQL API as MCP tools over streamable HTTP.

Connecting#


URL	`https://api.outeract.com/mcp`
Transport	Streamable HTTP (stateless)
Auth	Outeract API key as bearer token

Every request must carry an API key — there is no anonymous access, including tool listing:

Authorization: Bearer YOUR_API_KEY

The API key scopes the whole session to its application, and its scopes gate the tools exactly as they gate the GraphQL fields: events:read for event and conversation reads, users:read for user reads, events:write for sending messages and creating events/files, and users:write for creating and updating users.

Claude (custom connector)#

Add a custom connector in Claude settings, or for Claude Code:

{
  "mcpServers": {
    "outeract": {
      "type": "http",
      "url": "https://api.outeract.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor#

In ~/.cursor/mcp.json:

{
  "mcpServers": {
    "outeract": {
      "url": "https://api.outeract.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Tools#

The server exposes 13 curated tools. Destructive operations (deletes, identity transfers) and all org/app/key/webhook/platform configuration are deliberately absent.

Conversations#

Tool	Description
`conversation_context`	A conversation projected as an LLM-ready, chat-completions-style messages array — the flagship tool, see below
`conversations`	List conversations with pagination and search
`user_conversations`	All conversations a user participates in

Messaging#

Tool	Description
`send_message`	Send a message to a user or conversation (platform and sender inferred automatically; supports attachments, templates, and idempotency keys)

Events#

Tool	Description
`events`	Query events with cursor pagination and filtering (by user, conversation, event types, payload)
`event`	Get a single event by ID
`create_event`	Create a custom event (`custom.{category}.{action}`) in a user’s event stream

Users#

Tool	Description
`users`	Query users with search and cursor pagination
`identities`	Query platform identities (phone numbers, platform user IDs)
`create_user`	Create a user
`update_user`	Update a user’s name, system-user flag, or config

Files#

Tool	Description
`files`	Get file records by ID
`create_file`	Create a file (for use as a `send_message` attachment)

The `conversation_context` tool#

Reconstructing chat history for an LLM normally means paging events, resolving sender edges, joining identities, and re-deriving roles. conversation_context does all of that server-side and returns a ready-to-use transcript:

{
  "name": "conversation_context",
  "arguments": {
    "conversationId": "40a4b0d1-...",
    "limit": 50
  }
}

returns:

{
  "conversationId": "40a4b0d1-...",
  "participants": [
    {"userId": "...", "name": "Bot", "isSystemUser": true, "identities": ["whatsapp:+1000"]},
    {"userId": "...", "name": "Alice", "isSystemUser": false, "identities": ["whatsapp:+2000"]}
  ],
  "messages": [
    {"role": "user", "content": [{"type": "text", "text": "hi bot"}], "senderUserId": "...", "createdAt": "..."},
    {"role": "assistant", "content": [{"type": "text", "text": "hello alice"}], "senderUserId": "...", "createdAt": "..."}
  ],
  "hasMore": false,
  "oldestCursor": "..."
}

Roles — messages sent by the perspective user map to assistant, everyone else to user, system messages stay system. The perspective defaults to the conversation’s system user (your bot); override with perspectiveUserId.
Attachments — files become typed content parts (image or file) with URLs.
Windowing — returns the newest limit messages in chronological order. Pass oldestCursor from a previous result as beforeCursor to extend context further back.

The same projection is available as the conversationContext query on the Developer GraphQL API.

Operational notes#

Tool arguments use camelCase (matching the GraphQL schema); tool names are snake_case.
Requests count against the same rate limit as the Developer API (100 requests/minute per key by default).
The endpoint can be disabled server-side with the MCP_ENABLED environment variable.