Tawked MCP server

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, 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 for that one.

One model: an account token

Every connection holds one account token, 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.

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

In ChatGPT, open Settings → Apps & Connectors → Advanced settings, and turn on Developer mode.
Choose Create, name it Tawked, paste https://tawked.com/mcp, and choose OAuth authentication.
Sign in to Tawked and allow (below).

For Claude on the web and Claude Desktop:

Open Settings → Connectors, then Add custom connector.
Name it Tawked, paste https://tawked.com/mcp, then Connect.
Sign in to Tawked and allow (below).

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.

codex mcp add tawked --url https://tawked.com/mcp
codex mcp login tawked

~/.cursor/mcp.json

{
  "mcpServers": {
    "tawked": { "url": "https://tawked.com/mcp" }
  }
}

Then in Cursor’s settings, open MCP and choose Connect beside tawked.

.vscode/mcp.json

{
  "servers": {
    "tawked": { "type": "http", "url": "https://tawked.com/mcp" }
  }
}

Choose Start above tawked in the file, and accept the sign-in.

~/.codeium/windsurf/mcp_config.json

{
  "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), with the permissions and applications the assistant should have. Then:

Claude Code
Any MCP client

claude mcp add --transport http tawked https://tawked.com/mcp --header "Authorization: Bearer tk_acct_…"

{
  "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.

The docs MCP server’s setup on Agents and assistants 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:

{ "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: 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": "<id>"}`) 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 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:

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. 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.

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:

The assistant previews

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.

You say yes

The assistant shows you the preview and waits for your yes, in your own words. Nothing is sent until you confirm.

The assistant sends

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.
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).

Troubleshooting

The assistant says the server answered 401

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.

A tool I expected is missing

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.

A tool says the connection lacks a permission

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.

The server answered 403

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.

"confirm_id" is refused

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 send was refused after I confirmed

The checks run again at send time. The answer names the reason in the Errors page’s words: the customer opted out, the balance is too low, the template is no longer approved, or the number is disconnected.

Get started

Verify

Notifications

Email

Webhooks and errors

Partners

Build with AI

Tawked MCP server

One model: an account token

Connect your assistant

Allow it on Tawked

With an account token

The tools

When a call is refused

Reaching every operation

Named tools for common jobs

Several applications

When a person must act

Confirm before it sends

Safety

Limits

Troubleshooting

​One model: an account token

​Connect your assistant

​Allow it on Tawked

​With an account token

​The tools

​When a call is refused

​Reaching every operation

​Named tools for common jobs

​Several applications

​When a person must act

​Confirm before it sends

​Safety

​Limits

​Troubleshooting

One model: an account token

Connect your assistant

Allow it on Tawked

With an account token

The tools

When a call is refused

Reaching every operation

Named tools for common jobs

Several applications

When a person must act

Confirm before it sends

Safety

Limits

Troubleshooting