Connecting an AI assistant

Peleka runs an MCP server alongside the REST API. Where the REST API is for your own backend, MCP is for letting an AI assistant act on a workspace directly, inside a normal chat: draft a campaign, check whether a domain is warmed up enough to send today, build an automation from a plain-language description. The assistant calls the same underlying services the dashboard and API do; it's a different door into the same house, not a separate system with its own rules.

This page covers connecting a client and the permission model around it. For what the assistant can actually do once connected, see Tools.

Connecting

The MCP endpoint is:

https://api.peleka.io/api/v1/mcp

Point any MCP-compatible client at that URL. Claude and ChatGPT's connector settings both take a URL directly; for a client you're building yourself, the server advertises everything it needs via /.well-known/oauth-authorization-server at the domain root. Most MCP-aware OAuth libraries can discover /authorize, /token, and dynamic client registration from that alone, without you hardcoding paths.

What happens on first connect:

1. The client redirects the user to Peleka's /authorize endpoint.
2. That redirects into the dashboard's own consent screen, not the client's. If the user isn't logged in, they're sent to log in first.
3. Logged in, they pick which workspace to connect and whether the grant is read or write.
4. Approving redirects back to the client with an authorization code, which it exchanges for an access token.

There's no separate "MCP account" or API key to generate beforehand. The whole flow rides on the user's existing Peleka login, the same way any third-party OAuth integration would.

Scopes

Two scopes exist: read and write. read covers every lookup tool: contacts, analytics, segment membership, and so on. write adds everything that creates or changes data, from tagging a contact to sending a broadcast.

Granting write requires the user to be a workspace admin, not just a member. This mirrors the floor already in place for minting a write-scoped API key, and for the same reason: a write grant gives a connected client the same reach as a write API key, regardless of which tools it happens to call, so the bar for handing that out has to match. A member can still connect a client at read scope on their own.

What authenticates a request

The /mcp endpoint itself accepts three different credentials, not just an OAuth token:

• A dashboard session cookie (if you're hitting it from something already logged into the dashboard).
• An X-API-Key header, same key you'd use against the REST API. Useful if you're building your own MCP client and would rather skip the OAuth dance entirely.
• An OAuth Bearer token from the connection flow above.

Whichever one authenticates the request determines the scope: a session gets full access, an API key or OAuth token gets whatever scope it was issued with. Every write-scoped tool call is logged to an audit trail keyed to whichever credential made it, so a bad automation build or an unexpected send can always be traced back to what called it.

Requests are rate-limited to 60 per minute per connection.

Token lifetime

An OAuth access token lasts 1 hour. The refresh token that comes with it lasts 90 days, so a client that implements the standard refresh flow shouldn't need the user to re-approve anything in between; MCP clients like Claude and ChatGPT handle this automatically.

New tools show up on reconnect, not mid-conversation

A client fetches the tool list once, when a connection starts, and doesn't re-check it for the rest of that session. If Peleka ships a new tool while a conversation is already open, that conversation won't see it; starting a new one (or otherwise reconnecting the integration) is the fix, not troubleshooting the deploy.

This is standard MCP client behavior, not something Peleka's server can push around: the /mcp endpoint is stateless, a fresh connection on every request, so it always serves the current tool list immediately after a deploy. The delay is entirely on the client side, in how long an already-open session goes before it asks again.

Confirmation before anything irreversible

Sending or scheduling a broadcast can't happen in a single tool call. peleka_send_broadcast and peleka_schedule_broadcast both require a confirmationToken, which only comes from calling peleka_preview_broadcast_action first. That preview tool is read-only: it resolves the real recipient count and returns a token good for 5 minutes, tied to those exact details.

This isn't a suggestion the model can talk itself out of. The token is single-use and the server re-checks that the subject, sender, and recipient count at send time still match what was previewed — if the broadcast changed in between, or the token already got used, or it expired, the send is rejected server-side. A model can still choose to skip showing the user a preview before calling the confirm step, but it can't skip the confirm step itself; there's no path from "draft" to "sent" that doesn't pass through a token minted by the preview call.

Revoking access

Settings → Connected Apps in the dashboard lists every active connection for a workspace and lets an admin revoke one immediately. Revoking invalidates the access and refresh tokens right away; the next call the client makes fails, and it has to go through the consent screen again to reconnect. There's no propagation delay to wait out.