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

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

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`, `assign-conversation`, `remove-tag`, and `remove-custom-data` always require confirmation, including a single conversation, tag, or field. 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.
- Rate limit: 120 requests per minute per connection. On `429`, wait and retry.
- `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.