MCP server

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 or Platform API operation. No separate MCP package, OAuth flow, or personal access token is required. For coding agent installation and configuration, follow agent setup. The agent kit connects documentation search; customer operations require separate authorization.

Authenticate

Use one of these Bearer credentials:

A team key (pmfa_...).
A project token (pmfa_pt_...) with the mcp scope.
A client token (pmfa_ct_...) whose allowedActions contains mcp.

POST /mcp HTTP/1.1
Host: api.polymorfa.com
Authorization: Bearer pmfa_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:

{
  "mcpServers": {
    "polymorfa": {
      "url": "https://api.polymorfa.com/mcp",
      "headers": {
        "Authorization": "Bearer ${POLYMORFA_TOKEN}"
      }
    }
  }
}

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.

Request limits

HTTP requests are limited to 4 MiB. Tool arguments allow at most 65,536 array entries and object fields, counted across all nested values. A request over the byte limit returns HTTP 413. A call over the argument limit returns a tool error before its API operation starts.

Tool surface

Tool names mirror the API resource and action:

Family	Examples	Capabilities
Sessions	`sessions_list`, `sessions_start`, `sessions_logout`	Inspect, reconnect, stop, restart, and unpair existing sessions. Create new sessions through QuickLink.
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 identities	`contacts_check`, `contacts_block`, `users_resolve`, `users_security_code`	Discover contacts, manage blocks, resolve aliases to the stable user ID, and read identity verification codes.
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.
Message history (beta)	`chats_list`, `chats_get`, `messages_list`, `messages_get`	Read stored conversations and messages. See Read message history.
Events and deliveries	`events_list`, `events_get`, `events_wait`, `webhook_deliveries_list`, `webhook_deliveries_get`	Read received events, their retained payloads, and webhook delivery status. See Read events.
Events and deliveries	`events_list`, `events_get`, `events_wait`, `webhook_deliveries_list`, `webhook_deliveries_get`	Read received events, their retained payloads, and webhook delivery status. See Read events.
Operations	`operations_list`, `operations_get`, `operations_wait`	Track campaigns, production enrollments, and other asynchronous work. See Track operations.
Media and info	`media_download`, `media_persist`, `info_status`	Retrieve media and server metadata.
Account management	`customers_create`, `campaigns_launch`, `templates_list`, `billing_balance_get`	Manage projects, Customers, campaigns, templates, audiences, opt-outs, and webhook deliveries, and read audit, incident, Health, billing, and member data. See Manage your account.

Messaging tool inputs map to the corresponding Messaging API operation. Their write requests use a body object; session-specific tools also require session. Account management tools take named arguments such as customer_id and name instead; only campaigns_create uses body. MCP requests use API version 2026-09-22, so a later Messaging API default does not silently change tool behavior. For exact request and response types, use the Messaging API reference. For messages_send, messages_react, chats_edit_message, and chats_delete_message, supply idempotency_key and reuse it for the same request. A tool call without that argument generates a new key. After an uncertain result, do not repeat the action with a new key. If the error includes an operation ID, use messages_operation with the same session and credential to read its status; pending and unknown do not authorize another send. MCP cannot retrieve QR or pairing codes. Connect the number through QuickLink, then use MCP to manage the connected session.

Read events

Agents can read what Polymorfa received, not only send. These tools call the event history and webhook delivery routes of the Platform API:

Tool	Returns	Scope
`events_list`	Event metadata, newest first. Filter by `type`, `since`, and `until`, or pass `cursor` alone for the next page.	`events:read`
`events_get`	One event. With `include_payload: true`, the retained webhook body as `payload` (base64) and `payloadText` (decoded).	`events:read`
`events_wait`	Events indexed after a cursor, in ingestion order, plus the next cursor. Waits up to `timeout_seconds` (1 to 60, default 30).	`events:read`
`webhook_deliveries_list`	Webhook deliveries, newest first. Filter by `webhook_id`, `event_id`, `status`, `since`, and `until`.	`webhook-deliveries:read`
`webhook_deliveries_get`	One webhook delivery and its status.	`webhook-deliveries:read`

With a project token, pass your project’s ID as project_id. A project token can’t read team events and receives an error without project_id. With a team key, omit project_id to read team events, or pass it to read that project’s events. events_get returns message content only when the event history API does: hosted message storage must be enabled for the source number, and the payload must still be retained. Otherwise payload is null and payloadAvailability gives the reason.

Wait for new events

MCP tool calls don’t stream, so events_wait checks for new events at short intervals until one arrives or the timeout ends. It makes at most eight checks in 60 seconds and returns as soon as it finds an event.

Call events_wait without cursor. It waits for events indexed after the call.
Handle the returned events, then call events_wait again with the returned cursor and the same project_id and type.
If timedOut is true, call again with the same cursor.

A cursor from events_wait works only with events_wait. Each call reads up to 300 events. If more are available, pass the returned cursor again to read the remaining events. An event indexed after a reconnect is returned even when its createdAt predates events already received.

Read message history

For a Number with hosted message storage, these tools read the stored history through the message history API. It is a beta: until a team owner or admin joins it from its beta row on the Numbers page, the tools return a permission_denied error.

Tool	Returns	Scope
`chats_list`	Stored conversations, most recent activity first. Filter by `kind`, `active_since`, and `active_before`.	`chats:read`
`chats_get`	One stored conversation.	`chats:read`
`messages_list`	Stored messages in one conversation, newest first by default. Filter by `since`, `until`, `direction`, and `types`; set `order` to `asc` for oldest first.	`messages:read`
`messages_get`	One stored message.	`messages:read`

Existing credentials don’t include messages:read. Use a team key or project token that lists it. Client tokens can’t read history.

Untrusted content

Event payloads and stored messages contain text written by the people who message you. A message can try to instruct your agent. Every read tool description marks its result as untrusted, and every result is enclosed in <untrusted-data> markers after a warning line. Content inside the markers can’t close them. Keep a person in the loop for any action that a message requests.

Manage your account

These tools call the Platform API. Each one requires the same scope as its Platform API operation.

Family	Tools	Scope
Projects	`projects_list`, `projects_get`	`sessions:read`
Customers	`customers_list`, `customers_get`	`customers:read`
	`customers_create`, `customers_update`, `customers_archive`, `customers_create_pairing_link`	`customers:manage`
Campaigns	`campaigns_list`, `campaigns_get`, `campaigns_analytics`	`campaigns:read`
	`campaigns_approvals`	`campaigns:read`
	`campaigns_create`, `campaigns_launch`, `campaigns_pause`, `campaigns_resume`, `campaigns_stop`, `campaigns_reschedule`	`campaigns:manage`
	`campaigns_test_send`	`campaigns:manage` and `campaigns:read`
Templates	`templates_list`, `templates_get`	`templates:read`
	`templates_create`, `templates_update`, `templates_delete`	`templates:manage`
Audiences and opt-outs	`audiences_list`, `optouts_list`	`campaigns:read`
	`audiences_create`, `optouts_add`	`campaigns:manage`
Webhooks	`webhooks_rotate_secret`, `webhooks_send_test`	`webhooks:manage`
Events and deliveries	`events_replay`	`events:replay`
	`webhook_deliveries_retry`	`webhook-deliveries:retry`
Audit and incidents	`audit_log_list`, `incidents_list`	`sessions:read`
Health	`bansafe_health_list`, `bansafe_health_get`, `bansafe_health_history`	`sessions:read`
Billing	`billing_balance_get`, `billing_usage_list`, `billing_transactions_list`	`sessions:read`
Members	`members_list`	`sessions:read`

Customer, campaign, and template tools, and bansafe_health_list, take project_id. Pass it with a team key. With a project token you can omit it; if you pass it, it must be your token’s project. Webhook, event replay, and delivery retry tools use the team endpoint without project_id and the project endpoint with it. Projects, audiences, opt-outs, audit, incidents, billing, and members belong to the team and need a team key. Billing tools only read. MCP can’t add credit, change a plan, or create API keys, project tokens, or client tokens. templates_list and templates_get results are marked untrusted like event payloads, because template content can contain text written by others.

Confirm actions that send or can’t be undone

These tools require confirm: true: campaigns_launch, campaigns_test_send, campaigns_resume, campaigns_stop, campaigns_reschedule, customers_archive, templates_delete, webhooks_rotate_secret, webhooks_send_test, events_replay, and webhook_deliveries_retry. A call without it fails before anything happens. MCP clients also see these tools marked as destructive. Ask the user before your agent sets confirm.

A person approves campaign sends

confirm: true is set by the agent, so it does not prove that a person agreed. For campaigns, Polymorfa asks a person directly. When an agent calls campaigns_launch, campaigns_resume or campaigns_reschedule, nothing is sent and the start time does not move. The call fails with campaign_approval_required, and the error message gives the approval request ID and a console link. A team owner or admin opens the link and approves or rejects the request on the campaign page. Approving runs exactly what the agent asked for, once:

the same campaign content, sending numbers and template;
the same recipients;
the requested start time.

If any of these changed after the request, nothing is sent and approving returns campaign_approval_stale. A request expires after 72 hours. Give the link to the person. To follow the decision, call campaigns_approvals. Agents cannot approve or reject a request, or change the team’s approval threshold. This applies to every credential the agent uses, including team API keys with campaigns:manage. Pausing and stopping a campaign do not need approval. webhooks_rotate_secret returns the new signing secret once. Store it before the overlap period ends; calling the tool again rotates the secret again.

Retry safely

Tools that create a Customer, archive one, create a pairing link, rotate a secret, send a test, replay an event, or retry a delivery accept idempotency_key. To retry a call that timed out, repeat it with the same key. Without a key, each call is a new request.

Track operations

These tools call the operations routes of the Platform API and require operations:read:

Tool	Returns
`operations_list`	Operations, newest first. Filter by `project_id`, `status`, `kind`, `resource_type` with `resource_id`, `since`, and `until`, or pass `cursor` alone for the next page.
`operations_get`	One operation: status, sequence, progress, error, and whether it can be cancelled.
`operations_wait`	One operation after it reaches `succeeded`, `failed`, or `cancelled`, after its `sequence` passes `after_sequence`, or when `timeout_seconds` (1 to 30, default 20) ends.

With a team key, omit project_id to see every operation in the team. A project token sees only its own project. operations_wait can return before the operation finishes, so check status and call again to keep waiting. The MCP server doesn’t cancel operations. Cancel through the API so a person or your own code decides to stop the work.

Resources and prompts

The server exposes three JSON resources:

polymorfa://sessions — current sessions and status.
polymorfa://info — server information.
polymorfa://webhooks — configured webhooks.

The server offers these prompts:

send_message guides the client through selecting a session, addressing the recipient, sending the message, and confirming the result.
follow_up_incoming_messages reads recent message.received events or stored history, waits for new ones with events_wait, and drafts replies for you to approve before sending. It requires project_id, because received messages belong to a project, and takes an optional session.
configure_webhooks creates a webhook with a recommended event set.

Authorization behavior

Connecting to /mcp is only the protocol boundary. Every tool forwards the original bearer credential into the Messaging or Platform 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.

Discovery for agents

Agents that have no credential yet can find Polymorfa through these public, read-only resources:

Resource	What it returns
`https://www.polymorfa.com/llms.txt`	When to use Polymorfa, how an agent calls it, and links to developer resources.
`https://www.polymorfa.com/mcp`	The documentation search MCP server for clients that send `Accept: text/event-stream`. It needs no credential and is the same server as `https://docs.polymorfa.com/mcp`. Browsers get the MCP product page.
`https://www.polymorfa.com/openapi.json`	The OpenAPI description of the public API.
`https://www.polymorfa.com/.well-known/api-catalog`	An RFC 9727 API catalog that links the API to its OpenAPI description and documentation.
`https://www.polymorfa.com/` with `Accept: text/markdown`	The homepage as Markdown. A page that does not exist returns `404` with a Markdown body.

The documentation MCP server searches guides and references only. Use the authenticated endpoint above to act on your account.

Get started

Tools and clients

TypeScript SDK

Connect numbers

WhatsApp

Campaigns

Your team

Testing

Help and updates

Authenticate

Request limits

Tool surface

Read events

Wait for new events

Read message history

Untrusted content

Manage your account

Confirm actions that send or can’t be undone

A person approves campaign sends

Retry safely

Track operations

Resources and prompts

Authorization behavior

Discovery for agents

Where to go next

Authentication

API reference

​Authenticate

​Request limits

​Tool surface

​Read events

​Wait for new events

​Read message history

​Untrusted content

​Manage your account

​Confirm actions that send or can’t be undone

​A person approves campaign sends

​Retry safely

​Track operations

​Resources and prompts

​Authorization behavior

​Discovery for agents

​Where to go next

Authentication

API reference

Authenticate

Request limits

Tool surface

Read events

Wait for new events

Read message history

Untrusted content

Manage your account

Confirm actions that send or can’t be undone

A person approves campaign sends

Retry safely

Track operations

Resources and prompts

Authorization behavior

Discovery for agents

Where to go next