> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect MCP clients directly to Polymorfa's authenticated WhatsApp tool surface.

Polymorfa exposes a stateless Streamable HTTP Model Context Protocol endpoint at
`https://api.polymorfa.com/mcp`. Each tool follows the authentication, scope,
rate-limit, and API-version rules of its corresponding Messaging API operation.

No separate MCP package, OAuth flow, or personal access token is required.

## Authenticate

Use one of these Bearer credentials:

* An organization key (`titan_...`).
* A project token (`titan_pt_...`) with the `mcp` scope.
* A client token (`titan_ct_...`) whose `allowedActions` contains `mcp`.

```http theme={null}
POST /mcp HTTP/1.1
Host: api.polymorfa.com
Authorization: Bearer titan_pt_...
Content-Type: application/json
Accept: application/json, text/event-stream
```

An MCP client configuration typically looks like this; adapt the field names to your client:

```json theme={null}
{
  "mcpServers": {
    "polymorfa": {
      "url": "https://api.polymorfa.com/mcp",
      "headers": {
        "Authorization": "Bearer ${POLYMORFA_TOKEN}"
      }
    }
  }
}
```

<Warning>
  The credential grants the client real Polymorfa access. Prefer a project token with only the scopes required by the agent. Use a client token when the integration needs session-specific actions and limits.
</Warning>

## Tool surface

Tool names mirror the Messaging API resource and action:

| Family               | Examples                                                                    | Capabilities                                                |
| -------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Sessions             | `sessions_list`, `sessions_create`, `sessions_start`, `sessions_logout`     | Create, inspect, start, stop, restart, and unpair sessions. |
| Pairing              | `pair_qr`, `pair_code`                                                      | Retrieve a QR or request a pairing code.                    |
| Messages and chats   | `messages_send`, `messages_seen`, `messages_react`, `chats_edit_message`    | Send supported message types and manage message/chat state. |
| Groups               | `groups_create`, `groups_add_participants`, `groups_promote`, `groups_join` | Full group lifecycle and membership operations.             |
| Contacts and LIDs    | `contacts_check`, `contacts_block`, `lids_resolve`                          | Discover contacts, manage blocks, and resolve identifiers.  |
| Channels             | `channels_create`, `channels_follow`, `channels_mute`                       | Create and manage WhatsApp channels.                        |
| Presence and profile | `presence_subscribe`, `profile_set_name`, `profile_set_picture`             | Presence subscriptions and account profile updates.         |
| Labels               | `labels_create`, `labels_set_chat`                                          | Manage labels and chat assignments.                         |
| Webhooks             | `webhooks_list`, `webhooks_create`, `webhooks_delete`                       | Manage webhook configuration.                               |
| Media and info       | `media_download`, `media_persist`, `info_status`                            | Retrieve media and server metadata.                         |

Tool input shapes map to the corresponding Messaging API operation. Write requests use a
`body` object; session-specific tools also require `session`. MCP requests use
API version `2026-03-20`, so a later Messaging API default does not silently change tool
behavior. For exact request and response types, use the [Messaging API
reference](/api/overview).

## Resources and prompt

The server exposes three JSON resources:

* `titan://sessions` — current sessions and status.
* `titan://info` — server information.
* `titan://webhooks` — configured webhooks.

The `send_message` prompt guides the client through selecting a session,
addressing the recipient, sending the message, and confirming the result.

## Authorization behavior

Connecting to `/mcp` is only the protocol boundary. Every tool forwards the original bearer credential into the Messaging API route it calls, so that route's scope and policy checks still apply. MCP does not create a privileged bypass.

The HTTP transport is stateless. Reconnect for each protocol exchange instead
of relying on a persistent MCP session.

## Where to go next

<Columns cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Choose an organization, project, or client credential.
  </Card>

  <Card title="API reference" icon="brackets-curly" href="/api/overview">
    Inspect the exact operations and schemas behind tools.
  </Card>
</Columns>