MCP server

Pingo Notify speaks MCP (Model Context Protocol), so an AI assistant can operate a workspace directly: list connections, send WhatsApp messages, read a conversation, manage webhooks. You approve what it may do once, on a consent screen, and it never handles an API key.

Connect

Add one URL to the client, as a custom or remote connector:

https://api.pingonotify.com/v3/mcp

Everything after that is the protocol doing its job:

Connecting itself needs no plan, and it keeps working on an expired subscription — but sending does not. See Limits.

What the assistant gets

One workspace, fixed at consent

Everything the assistant sees belongs to the workspace you picked while authorizing. There is no tool to switch workspaces and no header it can send to change one: a request that tries answers 403 — This access token is bound to a different workspace; re-authorize to switch. A second workspace means a second authorization.

Scope is a ceiling, never a grant

The effective permission of a token is the intersection of the scopes you approved and what you can do in that workspace. Approving messages:send does not let an assistant send if your own role cannot; a scope only ever narrows.

You can always approve less than what was asked. Re-approving with fewer scopes revokes the tokens already issued to that integration, so the screen and reality never disagree.

It knows its own limits before it tries

The handshake carries a paragraph assembled for that token: the tools this access can use, and the ones it cannot, by name. An assistant that already knows it lacks webhooks:write tells you so instead of spending a turn discovering it.

Tools out of scope stay listed on purpose. Hiding them would turn a refusal that names the missing scope into an unhelpful "unknown tool".

The tools

Twenty-three tools. The cut is by domain, not by route — the helpdesk is out of scope by product decision.

Orientation

Start with list_connections, always. Every other tool needs a connectionId, and it is the tool that reveals the connection's type — which decides whether a sending tool works at all. It reports canSend too, which is true only while the connection is open.

check_whatsapp_number takes up to 50 numbers at once and returns the canonical id of each. get_workspace tells the assistant which scopes it actually holds.

Messaging

There is one tool per shape of message rather than one tool with a type field. A single schema with seven optional branches lets a model assemble a combination WhatsApp rejects — and that error arrives after the send was charged.

Webhooks

Rules that fail in silence

Worth reading before you let an assistant loose: ignoring these produces no error at all, just a result nobody gets.

• An official connection feeds a webhook less. Inbound messages (messages.upsert) and delivery updates (messages.update) do arrive there; send.message, messages.delete, messages.edited, presence.update and connection.update never do. Subscribing to them on an official connection produces silence, not a rejection.
• Two events are accepted at registration and never delivered on any connection: connection.update and presence.update. list_webhook_event_types carries that truth per event, which is why an assistant should call it before creating a subscription. For connection status, poll list_connections instead.
• A webhook with no connection linked never fires. create_webhook requires at least one connection id — pass every id if you want the whole workspace. The webhook is created active and list_webhook_deliveries comes back empty, which reads exactly like "wrong event".
• Your endpoint will see the same event more than once. Delivery times out at 10 seconds and is retried up to three times, one row logged per attempt. Make the endpoint idempotent; an endpoint that answers slower than 10 seconds guarantees duplicates.
• Phone numbers travel as international digits only — 5511999998888, no +, no spaces, no punctuation. For a number you have not messaged before, run check_whatsapp_number first and send the canonical id it returns rather than what the user typed.
• Already-hosted media goes by public https URL; a local file goes by upload. Base64 in the argument is not accepted, and that is not fussiness: once an image reached the assistant as an image, it is no longer a string it can hand back — and when the bytes do exist, writing them would consume the whole reply (1 MB of file is ~1.4 million characters). For a file on the assistant's machine, prepare_media_upload returns a single-use upload URL: it uploads the file with one curl -F 'file=@path' and the message is sent in that same request, without the bytes ever crossing its context. With no terminal available, the same URL lets you upload the file yourself.
• The media type is a choice, and the contact sees different things. An image shows in the bubble with the caption underneath; a video becomes a player with a thumbnail and plays inside the conversation; an audio is an attachment, with a play button and the file name beside it; a voice note is the round waveform bubble with 1x/1.5x/2x playback — what people mean by "send an audio"; a document is the card with an icon, file name and size that the contact downloads to open. Anything that is not an image, a video or an audio can only be a document. The assistant declares this type when it asks for the upload URL (or in mediatype, when sending by URL) — it is not guessed from the file extension, precisely so a video does not arrive as a file card.
• Sending costs the workspace money and cannot be undone. The server instructions tell the assistant to confirm with you before sending, unless you already asked for that send in the conversation.
• download_message_media gives up quietly on a big file. Above roughly 750 KB it answers with no content and a note telling the assistant to open the file in Pingo — a success, not an error. A client that only checks for failure will carry on with nothing in hand.
• send_whatsapp_template fills positional text variables only. A template whose parameterFormat is NAMED, or that has a media header or a dynamic button, cannot be filled through this tool — that one is the HTTP API. Meta rejects the whole send when the name, language or parameter count do not match.
• delay is in milliseconds and stops at 20000. It blocks on the WhatsApp side; higher values time the request out after the message was accepted — an error for the assistant, a delivered message for the contact.

Limits

The MCP bucket is keyed by credential on purpose. A remote MCP client is not called by your browser: the calls come from the infrastructure hosting the model, out of a handful of egress IPs. Keyed by IP, one workspace would throttle another.

What it deliberately will not do

The first two live in the dashboard, where there is a person.

When something goes wrong

A tool that fails comes back as tool content, readable, not as a protocol exception — so the assistant sees the reason and can correct course: ask you for another scope, warn you, try a different tool. Unexpected failures never leak detail; the stack and any database message stay in the log.

Building your own client

If you are writing the client rather than using one, four details save an afternoon:

• Ask for the refresh_token grant at registration. grant_types omitted means authorization_code alone, and then no refresh token is ever issued — your connector stops working an hour later and needs a human again.
• Send token_endpoint_auth_method: "none" to be a public client. Omitting the field creates a confidential client instead, which gets a client_secret shown exactly once and must send it on every token call.
• The first request needs Accept: application/json, text/event-stream. The MCP transport requires it, even though this server always answers JSON.
• The resource parameter scopes the token to a path. A token minted for https://api.pingonotify.com/v3/mcp is accepted under /v3/mcp and rejected with 401 everywhere else in the API. Ask for the resource you actually intend to call.

prompt=consent forces the screen even when a live consent already covers the request; prompt=none never shows it and answers consent_required or login_required instead. Otherwise a repeat authorization can complete silently — but only when exactly one existing consent covers the scopes asked for, and your role still allows it.