---
name: chatway-mcp
description: Work inside a Chatway workspace from an AI assistant over the Model Context Protocol. Use when connecting Claude, ChatGPT, Cursor, or another MCP client to Chatway, or when listing, searching, summarizing, replying to, tagging, assigning, or resolving Chatway conversations.
---

# Chatway MCP

Connect an MCP client to Chatway so it can work in the team's inbox. The server is remote and uses OAuth. Do not paste an API key into the client.

## Endpoint

- URL: `https://mcp.chatway.app/mcp`
- Transport: streamable HTTP
- Scope: `mcp:use`
- Authorization server: `https://mcp.chatway.app`
- Protected resource metadata: `https://mcp.chatway.app/.well-known/oauth-protected-resource`
- Authorization server metadata: `https://mcp.chatway.app/.well-known/oauth-authorization-server`
- Docs: https://developers.chatway.app/mcp/guides.mcp_overview

## Connect

1. Add `https://mcp.chatway.app/mcp` as a remote MCP server.
2. Leave OAuth enabled. Chatway uses OAuth 2.1 with PKCE and dynamic client registration. There is no client ID or secret to create.
3. Sign in as a workspace owner or admin.
4. Name the connection, then choose widgets, channels, and permissions. Write permissions can only be granted by an owner or admin.
5. Test with: "List my 5 most recent Chatway conversations."

A connection belongs to the team workspace. Re-authorizing the same client updates that connection. Owners and admins manage it under AI → External AI. Members cannot run the OAuth flow.

## Tools

Call only tools the connection was granted. Tools without a granted permission are not offered.

| 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` |
| Install on a website | `get-installation-code`, `get-installation-status` (no permission needed) |

`handoff-to-human` uses the same handover behaviour as Chatway's built-in AI agent.

To install Chatway on a website, call `get-installation-code` and add `script_html` once to a shared layout that loads across the site, inside `<head>` or `<body>`, preferably just before `</body>`. On Shopify, Wix, WordPress and other supported platforms, the native app or plugin also works. First check that the site does not already include a `<script id="chatway">` or `widget.js?id=` script. The installation ID is the account's, not a widget ID. After deploying, call `get-installation-status` with the domain: only `widget_operational` and `script_detected` confirm the installation. Call it without a domain to list the account's websites and its WhatsApp, Messenger, Instagram and email connections.

Access is limited to the widgets and channels selected during authorization. The connection cannot see other widgets or another team's data.

## Safety

- `resolve-conversation`, `unresolve-conversation` and `assign-conversation` with more than one conversation require confirmation. The tool returns `confirmation_required` and a `confirmation_token` instead of acting. Show the user that message and how much the action will affect, then retry with the token. Approval lasts 5 minutes and applies only to that exact action.
- Every other write, including those three tools on a single conversation, runs immediately within the connection's permissions. Only act when the user asked for it or it is part of a task they delegated.
- Rate limit: 120 requests per minute per connection. On `429`, wait and retry.
- Resolve, unresolve and assign: up to 30 conversations per call, and 30 conversations per minute for each action, per account. Over the limit, the tool returns an error with the seconds to wait; nothing is queued.
- `403 insufficient_scope` means the token lacks `mcp:use`. Remove the server from the client and add it again.
- Do not disable OAuth. For OpenCode, leave `oauth` unset and run `opencode mcp auth chatway`.

## When not to use MCP

Use webhooks plus the REST API when the same input must always produce the same result, or when a visitor message should trigger a reply automatically. MCP is for a person asking an assistant to work in the inbox. See the `chatway-api` and `chatway-webhooks` skills.
