- Docs
- Developers
MCP server for AI apps
Let AI apps work with your TalkingDot inbox. Connect Claude, ChatGPT, Claude Code, Cursor or n8n to the TalkingDot MCP server, then ask things like “summarise today’s unassigned chats”, “find the conversation about order 1042” or “reply to Cara that her parcel ships tomorrow”.
Overview
MCP (the Model Context Protocol) is the open standard AI apps use to call tools in other services. The TalkingDot MCP server gives an app tools to search and read conversations, contacts and help-center articles — and, if you allow it, to reply, add notes, assign, tag, close, reopen and snooze conversations. It works on every plan.
| Server address | https://talkingdot.com/mcp |
|---|---|
| Transport | Streamable HTTP (one JSON-RPC request per POST, plain JSON answers) |
| Sign-in | OAuth 2.1 in one click (Claude, ChatGPT, Claude Code…), or an API key in the Authorization header |
| Access | One workspace per connection: Read only or Read and act |
| Rate limit | 120 requests per minute per connection or API key (shared with the REST API for keys) |
Connect from Claude (claude.ai and Claude Desktop)
- In Claude, open Settings → Connectors.
- Click Add and choose Add custom connector.
- Give it a name (for example “TalkingDot”), paste
https://talkingdot.com/mcpas the URL and click Add. Leave the advanced OAuth fields empty. - Click Connect. A TalkingDot page opens: sign in (two-factor authentication works as usual), choose the workspace, choose Read only or Read and act, and click Allow access.
- Back in Claude, open the connector to switch individual tools on or off. In a chat, Claude asks before it uses a tool unless you allow it.
On Team and Enterprise plans, an owner of your Claude organisation may need to add the connector first. Claude connects from its own servers, so this works only with a site reachable from the internet.
Connect from ChatGPT
- In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode (in a workspace, an admin may have to allow it).
- Back in Apps & Connectors, click Create.
- Enter a name, a short description and
https://talkingdot.com/mcpas the MCP server URL, and choose OAuth as the authentication. - Click Create, then sign in on the TalkingDot page that opens, choose the workspace and the access, and click Allow access.
- In a chat, add the app from the + menu (or mention it) so ChatGPT uses its tools.
ChatGPT moves these settings from time to time and decides which plans may add custom apps; if a label differs, look for “Developer mode” and “Create app” in its settings.
Connect from Claude Code
Add the server, then sign in from Claude Code:
claude mcp add --transport http talkingdot https://talkingdot.com/mcpThen run /mcp inside Claude Code, choose the server and Authenticate: your browser opens the TalkingDot sign-in and consent page. To use an API key instead of signing in (for example on a server):
claude mcp add --transport http talkingdot https://talkingdot.com/mcp \
--header "Authorization: Bearer cn_live_xxxxxxxx"Connect from Cursor
Create an API key in Settings → Developers → API keys (choose Read only if Cursor should only read), then add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"talkingdot": {
"url": "https://talkingdot.com/mcp",
"headers": { "Authorization": "Bearer cn_live_xxxxxxxx" }
}
}
}Restart Cursor or reload its MCP settings; the tools appear under the server’s name.
n8n, Make and other apps
Any MCP client that takes a server address and a header works the same way: use https://talkingdot.com/mcp, the Streamable HTTP (“HTTP streamable”) transport, and the header Authorization: Bearer <API key>. In n8n, that is the MCP Client Tool node with bearer authentication. For workflows that react to new conversations or messages, use webhook subscriptions.
Under the hood every call is one JSON-RPC message. For example, listing the tools with an API key:
curl https://talkingdot.com/mcp \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2025-11-25" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Read only or Read and act
Every connection is for one workspace and has one of two levels. The level is checked on the server for every call — an app with read-only access never sees the write tools, and calling one anyway is refused.
| Level | The app can | How to get it |
|---|---|---|
| Read only | Search and read conversations (with messages and internal notes), contacts, help-center articles, teammates and tags. | Choose Read only when you connect, or use an API key created with Read only access. |
| Read and act | Everything above, plus reply to customers, add internal notes, assign and unassign, add and remove tags, close, reopen and snooze conversations. | Choose Read and act when you connect, or use a Read and write API key. |
The app works as the teammate who connected it (or who created the API key): replies and notes show that person as the author, and they appear in the inbox like any other. Only owners and admins of a workspace can connect apps to it — the same people who can create API keys.
Tools
| Tool | What it does | Level |
|---|---|---|
get_workspace | The workspace, its plan, the teammate the connection acts as, its access level and the open, unassigned and snoozed counts. | Read |
search_conversations | Conversations, newest activity first. Filters: status, assignee (me, unassigned or a teammate id), tag, contact_id, priority and text (the #number, the customer’s name, email or phone, or words in the messages); priority: true finds high and urgent ones. Each result has its priority_level and its ticket (or null). Paged with next_cursor. | Read |
get_conversation | One conversation by id or #number, with its customer and latest messages and internal notes (optionally timeline events). | Read |
search_contacts | Leads and users by name, email, phone, company or your own user id; by tag. | Read |
get_contact | One contact with location, custom attributes, tags and their latest conversations. | Read |
search_articles | Help-center articles by words (published, or drafts too). | Read |
get_article | One article as plain text or HTML, with its public link. | Read |
list_teammates | Teammates (id, name, email, role, availability) and teams. | Read |
list_tags | Tags with how many open conversations carry each. | Read |
list_payment_requests | A conversation’s payment requests (pay in chat): amount, what it is for, open, paid, expired or cancelled. | Read |
list_ticket_types | Whether tickets are on, the ticket types (with the fields each type’s form asks for), the custom fields, the statuses and the priorities: the values the other ticket tools take. | Read |
search_tickets | Tickets, most recent activity first. Filters: status (default unsolved: open, waiting on the customer or on hold), type_id, priority (low, normal, high, urgent), assignee, contact_id, overdue and text (a ticket number like #1042, or words in its title). Paged with next_cursor. | Read |
reply_to_conversation | Sends a reply to the customer, exactly like a reply from the inbox: in the chat, by email or on the messaging app the conversation came from (with that app’s rules, such as WhatsApp’s 24-hour window). Optional close_after and client_id (a retry with the same id never sends twice). | Act |
add_internal_note | A private note for the team, optionally mentioning teammates (they are notified). | Act |
assign_conversation | Assigns to a teammate (and optionally a team); they are notified. | Act |
unassign_conversation | Back to Unassigned (optionally without the team). | Act |
add_conversation_tags | Adds tags; new tag names are created. | Act |
remove_conversation_tags | Removes tags from the conversation. | Act |
close_conversation | Closes it (in the chat the customer may be asked to rate it, if ratings are on). | Act |
reopen_conversation | Opens a closed or snoozed conversation again. | Act |
snooze_conversation | Snoozes until 1h, 4h, tomorrow, monday, week or an ISO 8601 time. | Act |
convert_to_ticket | Makes a conversation a ticket, with an optional title, type_id, priority and fields. The ticket number is the conversation’s #number. The customer may get a “ticket created” email (only to a proven address, when the workspace sends them). | Act |
update_ticket | Changes a ticket’s status (open, waiting, on_hold, solved or closed), type_id, priority, title, fields or due_at (auto for the automatic one). Solving needs the fields required to solve; the customer may get an email for waiting, solved and closed. | Act |
Every tool has a JSON schema and MCP annotations (read-only, destructive, open-world) that apps can show or use when they ask you to confirm a call. get_conversation also shows the conversation’s priority_level and ticket, and close_conversation on a ticket marks it solved.
Locked conversations
Conversations that came in after a plan’s monthly limit are locked everywhere until the workspace is upgraded, and the MCP server is no exception: the tools show that they exist (number, status, the customer’s name) but never their messages, subject or the customer’s email, text search doesn’t look inside them, and they can’t be answered or noted.
Security
- You decide what the app gets. Signing in is the normal TalkingDot sign-in, with two-factor authentication. You pick one workspace and the access level; the app gets nothing else in your account. The consent page can’t be shown inside another site (no clickjacking) and sends the answer only to the return address the app registered.
- Short-lived tokens. Access tokens last an hour. Refresh tokens are replaced on every use; if an old one is ever used again, the whole connection ends. Codes work once, for five minutes, and only with the app’s PKCE secret. Tokens are stored only as hashes and are never put in a URL.
- It stops when your access stops. A connection ends for good when you leave the workspace or are removed, and pauses while your account is suspended or you are no longer an owner or admin — the same rule as API keys.
- Everything is logged. Every change an app makes is recorded in the workspace’s activity log with the app’s name and the teammate it acts as.
- Limits. 120 requests a minute per connection, and at most 10 replies to the same conversation in 5 minutes — a safety net if an AI gets stuck in a loop.
- Customer messages are untrusted text. The server tells the AI never to follow instructions found inside a message, but review what an AI sends on your behalf, especially with Read and act.
Disconnecting an app
Owners and admins see every connected app in Settings → Developers → Connected apps: who connected it, its access, when it was last used and whether it is paused. Disconnect ends it at once. Apps that use an API key stop when the key is revoked in Settings → Developers → API keys.
Technical details
| Protocol versions | 2026-07-28 (stateless: version and capabilities in each request’s _meta, mirrored in the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers; server/discover) and 2025-11-25, 2025-06-18, 2025-03-26 (the initialize handshake). No sessions; GET answers 405 (no event streams). |
|---|---|
| Protected resource metadata | https://talkingdot.com/.well-known/oauth-protected-resource/mcp (RFC 9728), also named in the WWW-Authenticate header of every 401 |
| Authorization server metadata | https://talkingdot.com/.well-known/oauth-authorization-server (RFC 8414) |
| Client registration | Client ID metadata documents (an https client_id), or dynamic client registration at /oauth/register (RFC 7591) |
| Flow | Authorization code with PKCE (S256 only) at /oauth/authorize and /oauth/token; refresh tokens rotate; revocation at /oauth/revoke (RFC 7009); the iss parameter is returned (RFC 9207) |
| Redirect addresses | https://, or http://localhost / http://127.0.0.1 for apps on your computer; matched exactly (a 127.0.0.1 address registered without a port may use any port) |
| Scopes | mcp:read, and mcp:write for Read and act. A read-only connection that calls a write tool gets 403 with error="insufficient_scope". |
| Tokens | Only for https://talkingdot.com/mcp (the resource parameter); Authorization: Bearer header only |