MCP overview

The Chatway MCP server lets an AI assistant — Claude, ChatGPT, Cursor, Codex, Grok, Muse, or anything else that speaks the Model Context Protocol — work inside your Chatway workspace using plain language.

Connect Chatway to an AI assistant

  1. Copy the MCP server URL:
https://mcp.chatway.app/mcp
  1. Add it as a remote MCP server in Claude, ChatGPT, Cursor, Codex, or another MCP client.
  2. Sign in to Chatway and choose the widgets, channels, and permissions the assistant can access.

That's it — no API key to paste. Client-specific steps are on Connect clients.

Test your connection by asking your assistant:

List my 5 most recent Chatway conversations.

MCP, webhooks, or the REST API?

Chatway offers three ways to connect an external system, and they solve different problems.

MCP Webhooks REST API
Direction Your assistant → Chatway Chatway → your server Your code → Chatway
What starts it You ask your assistant A visitor does something Your code decides
What decides the outcome The model Your code Your code
Do you write code? No Yes Yes
Auth OAuth Signed secret X-API-KEY
Set up in Your MCP client Settings → Developer Tools → Webhooks Settings → Developer Tools → API Keys

Choose MCP when a person wants to work through an assistant on demand — triaging a queue, summarising a thread, drafting a reply. There is nothing to build, and the model decides which tools to call, which is exactly why it suits open-ended work and not fixed rules.

Choose webhooks when something in Chatway should trigger your system in real time, most often so an agent can answer visitors automatically the moment they write in.

Choose the REST API when you want behaviour that is exact and repeatable, with no model in the loop: syncing conversations into your warehouse, provisioning contacts from your CRM, back-office scripts, scheduled reports, or your own dashboard. If a wrong call would be expensive, or the same input must always produce the same result, use the REST API rather than asking an assistant to do it.

They combine well. A common setup uses webhooks to notify an agent, the REST API for that agent to reply deterministically, and MCP so the support team can still ask questions in natural language over the same inbox. See the API Reference in the sidebar for endpoints, and Quickstart for the receive-a-message-and-reply loop.

What MCP gives you

Once connected, your assistant can work in your inbox conversationally:

"How many conversations are still unresolved on the marketing widget?"

"Summarise the last conversation with [email protected], then reply asking for their order number."

"Tag every conversation from today that mentions refunds."

It does this by calling tools you explicitly authorized. It never gets your password, and you never paste an API key into it.

The endpoint is a streamable HTTP MCP server and accepts POST requests. It is separate from the REST API: the REST API authenticates with an X-API-KEY header, MCP with OAuth.

Authentication

MCP clients use OAuth 2.1 with PKCE and request the mcp:use scope. Chatway supports dynamic client registration, so your client handles the whole exchange and you never create a client ID or secret.

  1. Your client discovers Chatway's authorization server from the MCP endpoint.
  2. A browser opens and you sign in to Chatway.
  3. You name the connection, so you can recognise it later.
  4. You choose which widgets and channels the assistant may access.
  5. You choose which permissions to grant, and which agent replies are sent as.
  6. Chatway issues an access token scoped to exactly those choices and returns you to your client.

Every connection belongs to your team workspace, not to an individual teammate. Owners and admins manage that connection under AI → External AI. Re-authorizing the same assistant client (for example Claude or Cursor) updates the team connection instead of creating a second one.

What assistants can do

Twenty-one tools are available. Each requires a matching permission, so an assistant only sees the tools you actually granted.

Group Tools
Read conversations list-conversations, get-conversation, list-conversation-messages, search-conversations
Read people get-visitor, search-contacts
Read settings search-knowledge-base, view-tags, view-custom-fields, list-agents
Reply and triage send-message, resolve-conversation, unresolve-conversation, assign-conversation
Annotate add-note, add-tag, remove-tag
Custom data add-custom-data, update-custom-data, remove-custom-data
Escalate handoff-to-human

handoff-to-human uses the same handover behaviour as Chatway's built-in AI agent, so your team gets the notifications and inbox state they already expect.

For each tool's parameters, return shape, and limits, see the Tool reference.

Scope of access

A connection can only reach the widgets and channels you selected. It sees nothing from your other widgets, and it can never reach data belonging to another team. Both are enforced on every request, independently of which permissions you granted.

Permissions also respect your Chatway role. Only owners and admins can run the MCP OAuth flow to connect or reconnect an assistant and open AI → External AI in Settings. Members do not have access to that menu. Write permissions on a connection can only be granted by an owner or admin.

Safety on bulk and destructive actions

Some actions ask for confirmation before Chatway will run them. Instead of acting straight away, the assistant has to put the question to you first, along with how much it is about to affect:

This action will resolve 100 conversations. Are you sure?

Confirm and it proceeds. Your approval lasts 5 minutes and is tied to that exact action, so an assistant cannot reuse it for anything else.

Confirmation is required for resolving, unresolving, or assigning more than one conversation at a time, and for removing a tag or removing custom data.

Rate limits

MCP requests are limited to 120 requests per minute per connection. Each connection has its own budget, so a busy assistant cannot slow down your other connections. Over the limit, the server returns 429 and the assistant should retry after a short pause.

Replying in real time with webhooks

MCP is on-demand: the assistant acts when you ask it to. If you want your AI agent to answer visitors automatically as soon as they send a message, use Chatway webhooks together with the REST API.

Visitor → Chatway → webhook → your AI agent → Chatway API → visitor

Chatway POSTs a signed event to your endpoint, your agent decides what to say, and it replies through the REST API. Alongside the reply your agent can record optional confidence and model details, which is useful for tracking how well it is performing before you let it handle everything.

You can also connect the same agent through MCP for on-demand access to your Chatway workspace — triaging the queue, summarizing threads, or taking actions in natural language. MCP is optional for the real-time loop above; webhooks and the REST API are enough on their own.

Thirteen events are available, including the ones most agents need:

Event Fires when
conversation.created A new chat has started
message.received A visitor sent a new message
conversation.resolved A conversation was resolved
agent.assigned An agent was assigned to a conversation
contact.form.submitted A visitor submitted a contact or offline form

Your agent can then use the REST API to reply, resolve, unresolve, star, assign, note, tag, update custom data, or trigger a human handoff — the same actions available over MCP.

Set this up under Settings → Developer Tools → Webhooks, and see Webhook docs → Overview in the sidebar for the full event list, payload shapes, signature verification, and retries. Quickstart walks through the receive-a-message-and-reply loop end to end.

Next steps