> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tawked.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tawked MCP server
> Let Claude, ChatGPT, Cursor, Codex, Claude Code or any MCP client work in your Tawked account: everything you do in the console through the Account API, as you and never more, with your yes before anything that sends, spends or deletes. Connect by signing in, or with an account token.
The Tawked MCP server lets an AI assistant work in your Tawked account with you. Ask it to draft a WhatsApp template, submit it to Meta and tell you when it is approved; to add a member or someone to the support team; to add an e-mail sending domain and check its DNS; to find out why a template was rejected; or to send an order update to a customer after you confirm. It does what you do in the console, through the [Account API](/account-api/overview), as you and never more, and only within the access you give it.
| Server | URL | What it can do |
| - | - | - |
| Read and act | `https://tawked.com/mcp` | Read and act within the access you gave |
| Read only | `https://tawked.com/mcp/readonly` | Read only, whatever the access: every tool that writes, sends or deletes is left out, and only reads run |
Connect to `https://tawked.com/mcp`: what the assistant may do is chosen when you sign in, or by the token you give it. The read-only address holds a connection to reading whatever its access.
This is a different server from the docs MCP server at `https://docs.tawked.com/mcp`, which searches this documentation, needs no key, and can do nothing on your account. See [Agents and assistants](/agents) for that one.
## One model: an account token
Every connection holds one [account token](/account-api/overview#account-tokens), and every tool runs an Account API operation with it: the same routes, the same rules, the same record as a call your own code makes. The token acts as the person it belongs to, never beyond what their role lets them do in the console, narrowed by its permissions and applications.
* **Signing in** makes the token. The assistant opens Tawked's consent page, you choose its applications and what it can do, and Tawked makes a token tied to that assistant and to you. You never see or copy it. It shows under **Settings → Account API**, marked **Assistant**: its page names the assistant, and there you change its permissions, applications and approvals, or revoke it. An assistant that signed in before the Account API keeps only reads (Verify, WhatsApp) until you allow more there or sign it in again.
* **A token you made** goes in the assistant's own settings, as `Authorization: Bearer tk_acct_…`. It keeps the settings you gave it, its approvals included.
The step-by-step for each assistant, with the prompt to give it, is in the [quickstart](/account-api/quickstart).
**Keys typed into an assistant stop working after 15 November 2026.** Until then, an application key made on the **AI assistants** page keeps working on its one application, with the named tools its access allowed. Replace it: connect the assistant by signing in, or make an account token under **Settings → Account API** and put it in the assistant's settings, then revoke the key on the **AI assistants** page. From 16 November such a key answers `401 mcp_key_retired`.
## Connect your assistant
1. In ChatGPT, open **Settings → Apps & Connectors → Advanced settings**, and turn on **Developer mode**.
2. Choose **Create**, name it Tawked, paste `https://tawked.com/mcp`, and choose **OAuth** authentication.
3. Sign in to Tawked and allow (below).
For Claude on the web and Claude Desktop:
1. Open **Settings → Connectors**, then **Add custom connector**.
2. Name it Tawked, paste `https://tawked.com/mcp`, then **Connect**.
3. Sign in to Tawked and allow (below).
```bash theme={"dark"}
claude mcp add --transport http tawked https://tawked.com/mcp
```
Then type `/mcp` in Claude Code, choose **tawked**, then **Authenticate**: your browser opens on Tawked.
```bash theme={"dark"}
codex mcp add tawked --url https://tawked.com/mcp
codex mcp login tawked
```
```json ~/.cursor/mcp.json theme={"dark"}
{
"mcpServers": {
"tawked": { "url": "https://tawked.com/mcp" }
}
}
```
Then in Cursor's settings, open **MCP** and choose **Connect** beside tawked.
```json .vscode/mcp.json theme={"dark"}
{
"servers": {
"tawked": { "type": "http", "url": "https://tawked.com/mcp" }
}
}
```
Choose **Start** above tawked in the file, and accept the sign-in.
```json ~/.codeium/windsurf/mcp_config.json theme={"dark"}
{
"mcpServers": {
"tawked": { "serverUrl": "https://tawked.com/mcp" }
}
}
```
Refresh the server list, and sign in when asked.
The same steps are on each application's **AI assistants** page in the console (**Integrations → AI assistants**).
### Allow it on Tawked
The assistant opens Tawked's consent page (sign in first if you are not). It shows who is asking, with **Verified** only when the sign-in returns to the assistant's own site (Claude, ChatGPT, Cursor, VS Code), and the request's details: the assistant and where it returns, your account, the time and your IP address. Choose:
* **Applications**: the ones it works on (tick one, several, or **Select all**), or every application, and the ones you add later.
* **What it can do**: **Everything you can do** (it works in your account as you do in the console, and asks you in the chat before anything that sends, deletes or spends), or **Read only** (it reads your account and applications and changes nothing).
Choose **Allow** and the assistant is connected; **Deny** sends it away with nothing. Allow only a connection you started yourself. Only a person who can open the console can connect an assistant.
One assistant holds one connection per person: signing it in again replaces its earlier access. A sign-in lasts an hour at a time and the assistant renews it by itself; after 60 days without use, or once disconnected, it signs in again.
### With an account token
For Claude Code, a script, or any client that sends a header: make a token under **Settings → Account API** in the console (see [Account tokens](/account-api/overview#account-tokens)), with the permissions and applications the assistant should have. Then:
```bash theme={"dark"}
claude mcp add --transport http tawked https://tawked.com/mcp --header "Authorization: Bearer tk_acct_…"
```
```json theme={"dark"}
{
"mcpServers": {
"tawked": {
"type": "http",
"url": "https://tawked.com/mcp",
"headers": { "Authorization": "Bearer tk_acct_…" }
}
}
}
```
The token's reveal in the console shows both, with the token already filled in. Keep the token in the client's settings or an environment variable, never in the chat. A token that asks first (**Ask me first**) sends each consequential call to the console's approval instead of the chat's preview: see [Confirm before it sends](#confirm-before-it-sends).
The docs MCP server's setup on [Agents and assistants](/agents) uses the same name, `tawked`. To keep both in one assistant, give one of them another name, such as `tawked-docs`.
Then ask your assistant: "What can you do in my Tawked account?" It calls `get_context` and answers with who it acts for, its permissions, the applications it reaches, what is left to set up, and whether you confirm in the chat or in the console.
## The tools
A connection lists the named tools its token's permissions allow, and on the read-only address only the reads. `call_tawked_api` is listed on `https://tawked.com/mcp` whatever the token holds (never on the read-only address), so a permission the person allows in the middle of a conversation works at once through it: until then the call answers `insufficient_permission` with the link to allow it. A named tool for that permission appears the next time the client reloads its tools. A tool that is listed checks again before it acts.
Every answer carries at most one hint, `next`, at the top of the answer: what to call next, said as the tool to call (the named tool when there is one, else `read_tawked_api` or `call_tawked_api` with the operation's id) and, for a wait, how often. A refusal carries one too, naming the tool, never a REST operation or header.
The tool descriptions are short: one or two sentences each, and a template's fields are described and bounded once, on `create_whatsapp_template` (`check_whatsapp_template` and `update_whatsapp_template` take them by type, and the check answers a field out of bounds as one of its problems). The whole `tools/list` answer of a full connection stays under 13 KB, at least 1 KB under 14 KB. What every tool shares is said once, in the server's instructions to the assistant: the preview and `confirm_id` flow and the approval flow, the generic tools' `operation`, `path`, `body` and `query`, pages of 10 with `next_cursor` passed back as `cursor`, times in Riyadh, money in halalas, and the template and send flows.
### When a call is refused
Every tool answers a refusal in one shape, a tool error whose structured content is `error` (a stable code), `message` (what was refused), `next` (what to call or do instead, naming the tool) and, when only a person can lift it, `human_action`, the text saying the same. It is the same whether the Account API refused the call (with its other facts beside them: `status`, `fields`, `needs`, `parameter`…), the server refused it (an unknown operation, a used or expired `confirm_id`, a call that names no application on a connection of several) or its arguments did. A human action's `then` is said as the tool to call, like `next`: `read_tawked_api (operation approvals.show)`, never a REST id. A field's message in `fields` is in English, like `message`, whatever the connection's language.
Every tool checks its arguments against its own input schema before it runs anything: a missing or empty required argument, a wrong type, a value outside its list (in any case), a pattern, a length or a bound, and the fields inside a list (such as `buttons.0.parameter`). The refusal names the argument as the tool calls it, with what it takes:
```json theme={"dark"}
{ "error": "invalid_argument", "argument": "message_id", "message": "message_id is required: the id send_whatsapp_message or list_whatsapp_messages returned.", "next": "Call get_whatsapp_message again with message_id as its description says." }
```
A path value its route does not take (a template's name where its numeric id goes) is answered as REST answers it, and nothing runs: `404 not_found` with the `parameter`, what it is, and the tool that lists its values (`list_whatsapp_templates` for a template).
### Reaching every operation
Four tools reach the whole [Account API](/account-api/overview): every operation the token may call, which is everything the person may do in the console within the token's permissions and applications.
| Tool | What it does | Read-only |
| - | - | - |
| `search_tawked_api` | Finds operations by a few English words (`query`, such as "whatsapp template create" or "email domain") and optionally an `area`, best matches first. Each result has its id, method, path, summary, permission, the tool that runs it (`tool`, and `named_tool` when a tool is made for the job), whether it is consequential, and `allowed`; when `allowed` is false, `needs` names the permission the connection lacks. On the read-only address it lists reads only. An empty query lists them all | Yes |
| `describe_tawked_operation` | One operation by its id (`operation`): the same description as the REST `GET /v1/operations/{id}` (its path parameters, the JSON Schema of its body or query, `allowed`, and for an operation the connection cannot call, `needs` with the `grant_permission` link to the token's page), plus the tool that runs it, how to fill it, `named_tool` when this connection lists a named tool for it, and a `next` naming that tool (for a consequential operation, with its preview and the person's yes, or the approval in the console). The `parameters` it answers say what each path parameter is and the operation that lists its values. An unknown id answers the nearest ones ("Did you mean …") | Yes |
| `read_tawked_api` | Runs one read (a `GET`) as the person: `operation`, `path` (the path parameters, such as `{"application": ""}`) and `query`. It never changes anything, so a client does not ask the person before each read | Yes |
| `call_tawked_api` | Runs one write (`POST`, `PUT`, `PATCH` or `DELETE`) as the person: `operation`, `path`, and `body` (or a `DELETE`'s `query`), plus `confirm_id` or `approval_id` for a consequential one | No |
The assistant works in a loop: `get_context` first, then `search_tawked_api` for the job, `describe_tawked_operation` for its input, and `read_tawked_api` or `call_tawked_api`. The answer is the operation's own JSON with its HTTP status, or the API's `error`, `message` and `fields`, with the same [errors](/account-api/overview#errors) as REST. The `application` path parameter may be left out when the connection reaches one application.
An operation that takes a file (an image, a logo) cannot be called through these tools: the tool says so, and the REST API takes it as `multipart/form-data` with an account token.
### Named tools for common jobs
The common jobs have tools of their own, each running its Account API operation with a shape written for a chat. They take the permission of their operation.
| Tool | What it does | Permission | Read-only |
| - | - | - | - |
| `get_context` | Who the connection acts for, what the person may do (`capabilities`, a list), the applications it reaches with their products and review state, what is left to set up (`next_steps`: per unfinished guide, how far it got, the step to take now with its operation or the person's action, and the steps left), the WhatsApp number's state, and whether a consequential action is confirmed in the chat or the console (`connection.confirms_in`), and `next`, the tool for the first step left. Each item of the number's `go_live` list has its `state` (`done`, `todo` or `blocked`); an item Tawked could not read yet is `todo`, and `whatsapp.go_live.check` reads it again. The application's `console_url` is in the connection's language. It does not repeat the tool list (the client's own list is the one) or what another field already says, and empty fields are left out, so it stays under 3 KB | None | Yes |
| `get_usage` | Per product, for a period: Verify codes sent, delivered and verified, WhatsApp messages sent, delivered and read, and what the balance was charged | `verify:read` or `whatsapp:read` | Yes |
| `list_whatsapp_templates` | Templates with Meta's status, category, language, quality and rejection reason; filter and search | `whatsapp:read` | Yes |
| `get_whatsapp_template` | One template: its parts, variables, status, quality and reason, and whether it can be sent or edited now | `whatsapp:read` | Yes |
| `check_whatsapp_template` | Runs the console's template checks on a proposed text template and saves nothing. It takes `create_whatsapp_template`'s fields, and every category, `AUTHENTICATION` included | `whatsapp:write` | Yes |
| `create_whatsapp_template` | Saves a text template as a console draft or, with `submit: true`, submits it to Meta; returns its console page. A submitted one is read with `get_whatsapp_template` every 30 to 60 seconds until Meta decides | `whatsapp:write` | No |
| `update_whatsapp_template` | Replaces the content of an approved, rejected or paused text template, with `create_whatsapp_template`'s fields. Meta reviews it again | `whatsapp:write` | No |
| `preview_delete_whatsapp_template` | Shows what deleting a template does, and what in Tawked sends it today, and returns a `confirm_id` | `whatsapp:write` | Yes |
| `delete_whatsapp_template` | Deletes the template at Meta, with the `confirm_id` | `whatsapp:write` | No |
| `preview_whatsapp_message` | Renders a template message for a recipient, runs the send's checks, states the price, and returns a `confirm_id` | `whatsapp:write` | Yes |
| `send_whatsapp_message` | Sends the previewed message, with the `confirm_id`. Its `next` is one sentence: tell the person, then read `get_whatsapp_message` every 5 to 10 seconds until the message is delivered, read or failed | `whatsapp:write` | No |
| `get_whatsapp_message` | The status of one message, with the reason when it failed | `whatsapp:read` | Yes |
| `list_whatsapp_messages` | Recent messages, numbers masked | `whatsapp:read` | Yes |
| `send_test_code` | A Verify code to the account owner's verified phone, and no other, in `language` (`ar` or `en`; `lang` is kept as another name for it). Takes `approval_id` when the person approves in the console. A wallet that cannot pay for the code is refused before any approval is asked | `verify:write` | No |
| `check_code` | Checks a code sent to the account owner's phone. It uses one of the verification's attempts. Its `next` follows the answer: a right code worked; a wrong code means asking the person to read the code again, with the attempts left; no attempts left, or a code that can no longer be checked, means `send_test_code` for a new one | `verify:write` | No |
| `get_verification` | The status of one verification | `verify:read` | Yes |
| `list_verifications` | Recent verifications, numbers masked | `verify:read` | Yes |
The previews and `check_whatsapp_template` send and delete nothing, but they lead only to a write, so the read-only address leaves them out (with `confirms_in` `console`, a preview also asks for the approval). `update_whatsapp_template` and `delete_whatsapp_template` are marked destructive. `check_whatsapp_template` answers each problem once, as `level`, `field`, `code` and `problem` (the sentence to show).
The server also offers the template rules and the Verify API as resources (`tawked://docs/whatsapp-template-rules` with `whatsapp:read`, `tawked://docs/verify-api` with `verify:read`), and a prompt, `write_whatsapp_template`, that walks the assistant through a template Meta will approve (with `whatsapp:write`).
### Several applications
Connected to more than one application, the assistant names the one each call is about: every named tool, and the `write_whatsapp_template` prompt, then takes an `application` argument, the application's id, and `read_tawked_api` and `call_tawked_api` take it in `path`. `get_context` without it lists the applications; with it, it answers for that application. A call without it, or for an application the connection does not reach, is refused with the list. A `confirm_id` works only on the application it was previewed on. Connected to one application, no tool needs the argument.
## When a person must act
Some steps are only yours: connecting a WhatsApp number in Meta's window, paying by card, a code sent to your inbox, a permission the connection lacks, something your role may not do. The tool's answer then starts with what the assistant must tell you:
```text theme={"dark"}
A person must act before this can go on (human_action: top_up_wallet).
Tell them: "Open this link to top up your Tawked balance with at least 50 SAR, then tell me when it is done."
Link to give them: https://tawked.com/en/dashboard/wallet/top-up?amount=50
When they say it is done, call read_tawked_api (operation wallet.balance.show) to check, then go on.
```
The assistant relays the sentence and the link, waits for you, then checks. Every reason is in [The person in the loop](/account-api/person-in-the-loop). The sentences meant for you, and the console links beside them (a human action's link, `get_context`'s `console_url`, the draft link `create_whatsapp_template` answers), are in the language of the client's `Accept-Language` when it sends one, else in your own language in Tawked; the server's instructions to the assistant are in English.
## Confirm before it sends
Anything that sends to customers, spends money, deletes or cannot be undone waits for your yes. Where you give it depends on the connection's token, and `get_context` says which (`connection.confirms_in`, called `confirms_in` below):
* **In the chat** (`chat`): an assistant's sign-in, or a token with **Act without asking**. The first call runs nothing and answers a preview with a `confirm_id`; the assistant shows it to you and waits for your yes in your own words, then calls again with the `confirm_id`.
* **In the console** (`console`): a token with **Ask me first**, or a sign-in whose approvals you turned on. The first call asks for the approval and answers that nothing has run, with the link to the approval's page in the console. `preview_whatsapp_message` and `preview_delete_whatsapp_template` ask it together with their preview, and answer the preview, the `approval`, its link and a `confirm_id`; `call_tawked_api` and `send_test_code` ask it on their first call. Once you approve it there, the assistant calls the doing tool again with the same input (and the preview's `confirm_id`, which then lasts as long as the approval: `preview_whatsapp_message` answers its `expires_at` and `preview_delete_whatsapp_template` its `expires_in_seconds`) and the `approval_id`. A preview's `confirm_id` carries the approval it asked: called without `approval_id`, the doing tool answers that approval (still waiting: its id, its state and how to call again with it; approved: it runs once under it), and never asks a second one. See [Approvals](/account-api/person-in-the-loop#approvals).
A held call is known by its error code, `approval_required` (HTTP `428` in the Account API), never by its status: it ran nothing. Its answer has no `message`; its `next` says how to call the same tool again with `approval_id` once the person approved, and not to try again if they declined.
In the chat, with the named tools:
It calls `preview_whatsapp_message` (or `preview_delete_whatsapp_template`). The answer shows exactly what will happen: the rendered message, the recipient (masked), the price, and the checks it passed. Quiet hours, a second marketing message to the same customer within the day, or no recorded opt-in come back as warnings to show you. It carries a `confirm_id`.
The assistant shows you the preview and waits for your yes, in your own words. Nothing is sent until you confirm.
It calls `send_whatsapp_message` (or `delete_whatsapp_template`) with the `confirm_id`, and nothing else.
With `call_tawked_api`, the call without `confirm_id` is the preview (the operation, its summary, the exact path and input, and, for a call on a campaign, an automation, the auto-attendant or a template draft, that draft as `acts_on`), and the same call with it runs the operation. The `confirm_id` is bound to the draft as shown: a draft edited since the preview is refused, and the assistant previews again.
A `confirm_id` works once, for 10 minutes in the chat (as long as the approval, 24 hours, when `confirms_in` is `console`), with the same token and the exact input that was previewed. Change the message and the assistant must preview again. The send runs the checks again, and refuses if anything now blocks it or the rendered text or price changed. A repeated `send_whatsapp_message` or `delete_whatsapp_template` with a used `confirm_id` returns the first result and does nothing more; with `call_tawked_api` a used `confirm_id` is refused and runs nothing again (read the result with the matching read operation).
With `confirms_in` `chat`, `send_test_code` is the one tool that sends in one call: it reaches only the account owner's own verified phone, never a number the assistant gives it, and Verify's hourly limit to one phone holds it. With `console`, it asks for the approval first like the rest.
## Safety
* **As you, never more.** The assistant acts as the person who connected it: their role, their applications, and the token's permissions on top. It cannot do anything that person could not do in the console.
* **The same rules as the API.** A message sent through the server goes through the same checks as one your code sends: approved templates only, a customer who opted out of marketing is refused, and your balance pays for it. A Verify test code reaches the account owner's phone only, and `check_code` checks only codes sent there.
* **Numbers are masked.** Every phone number a named tool returns is masked, except your own WhatsApp sender number.
* **Text from outside is data.** An answer that holds text written outside the account (a customer's message, a page read from the web, a store's data) starts with a line telling the assistant to treat it as data, never instructions. Read the preview yourself before you confirm a send, whatever the assistant concluded. See [Text from outside the account](/account-api/security#text-from-outside-the-account).
* **No secrets in the chat.** The assistant never asks for a token, a key or a password in the conversation: a token lives in the assistant's own settings.
* **Everything is recorded.** Every call is in the token's activity (its page under **Settings → Account API**, and `account.tokens.activity`) and in **Last calls** on the application's **AI assistants** page, and every change in the account's record, under the assistant that made it.
* **Cut it off.** **Disconnect** an assistant on an application's **AI assistants** page, or revoke its token under **Settings → Account API** (or with `account.tokens.revoke`). Its sign-in ends with it: it stops at its next call, on every application it reached, and signs in again only through the consent page.
* **Browsers from known sites only.** A call that carries an `Origin` header from a site other than Tawked, Claude or ChatGPT is refused with `403 origin_not_allowed`.
## Limits
* **120 calls a minute per connection**, and **10 a minute** on the tools that send or delete (`send_whatsapp_message`, `send_test_code`, `delete_whatsapp_template`, and `call_tawked_api` with a `confirm_id` or an `approval_id`). Past the limit the server answers `429`; wait and try again. The Account API's own limits apply too: 300 calls and 60 writes a minute per token.
* **10 minutes** for a `confirm_id` in the chat, used once; with `confirms_in` `console`, as long as the approval it asked (24 hours).
* **Last calls** are kept 90 days.
* **Stays with a person**: connecting a WhatsApp number (Meta's window), paying by card, approving a request, and making or widening a token. The assistant gets the console link and gives it to you (see [When a person must act](#when-a-person-must-act)).
## Troubleshooting
The answer's `error` says why. `invalid_token`: the sign-in expired or the assistant was disconnected; connect it again from the assistant. `unauthorized`: the account token is unknown. `token_revoked` or `token_expired`: the account token no longer works; the answer carries the `new_token` `human_action`, the link where the person makes a new one to put in the assistant's settings. `mcp_key_required`: an ordinary API key or a partner key, which never opens the server. `mcp_key_retired` or `key_expired`: a key typed into an assistant that no longer works; sign in, or use an account token.
The connection's token lacks its permission (the tables above), or the assistant is on the read-only address. `search_tawked_api` still finds the operation, with `allowed: false` and the permission it `needs`, and `describe_tawked_operation` gives the link. Give the token the permission on its page under **Settings → Account API** (an assistant's sign-in has its page there too), or connect the assistant again and choose **Everything you can do**. A token with no write permission, such as an assistant that signed in before the Account API, lists no named write tools, but `call_tawked_api` is always there: once the person allows the permission, call the operation through it, and the named tool appears when the client reloads its tools. A key typed into an assistant never lists the four tools that reach every operation.
The answer starts with what to tell you and the link to the token's page, with the permission chosen: allow it there, and the assistant calls the same operation again through `call_tawked_api` (or `read_tawked_api`), which works at once. An assistant that signed in can also be connected again with **Everything you can do**.
`origin_not_allowed`: the call came from a browser on a site the server does not accept. A tool's own `403` comes from the Account API: `insufficient_permission`, `forbidden` (your role may not; the answer names the owner), `ip_not_allowed` (the token is limited to other addresses, and assistants hosted by Claude or ChatGPT call from their own), `account_suspended` or `onboarding_incomplete`.
Only a person who opens the Tawked console can connect an assistant, in an account that is active. Ask the account owner.
It is older than 10 minutes (or, when you approve in the console, its approval expired), was made by another connection, or the input or the draft it acts on changed since the preview. Ask the assistant to preview again.
The checks run again at send time. The answer names the reason in the [Errors](/errors) page's words: the customer opted out, the balance is too low, the template is no longer approved, or the number is disconnected.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.