Convot MCP server

An MCP server that lets an AI agent operate a Convot inbox over the public REST API: read and reply to conversations, manage contacts, look up team availability, and search the help center.

It is a curated 13-tool surface, not a 1:1 dump of the API. Admin CRUD (article / changelog / roadmap writes), webhook subscriptions, and binary uploads are left out on purpose - they are app-to-app plumbing, not things an agent does.

Tools

| Tool | What it does | |---|---| | list_conversations | List conversations (filter by status / contact) | | get_conversation | Get one conversation by UUID | | create_conversation | Start a thread by contact_id or email | | resolve_conversation | Mark resolved | | reopen_conversation | Reopen | | list_messages | Read a thread (cursor-paginated) | | send_message | Reply into a conversation | | search_contacts | Find a customer by name/email | | get_contact | Full contact profile + custom data | | upsert_contact | Find-or-create by email/external_id | | list_agents | List agents + live online status (discover operator_ids) | | search_articles | Fuzzy help-center search | | get_article | Full article body |

Install

Published to npm and run on demand via npx - nothing to clone or build. Needs Node.js 18+. Your MCP client (below) launches it for you; to run it standalone:

npx -y convot-mcp

Get an API key from the dashboard under App Settings → API Keys. It has the form prefix:secret and is shown once. The key is scoped to a single app.

Required scopes for the full tool set: conversations:read/write, messages:read/write, contacts:read/write, helpdesk:read, agents:read.

Configuration

| Env var | Required | Default | |---|---|---| | CONVOT_API_KEY | yes | - | | CONVOT_BASE_URL | no | https://app.convot.io/v1 |

Use it with a client

Claude Code

claude mcp add convot --env CONVOT_API_KEY=prefix:secret -- npx -y convot-mcp

Claude Desktop / generic MCP config

{
  "mcpServers": {
    "convot": {
      "command": "npx",
      "args": ["-y", "convot-mcp"],
      "env": { "CONVOT_API_KEY": "prefix:secret" }
    }
  }
}

Develop

Build from source (contributors):

cd mcp
npm install
npm run build
npm run dev      # tsc --watch
npm run inspect  # @modelcontextprotocol/inspector against the built server

Errors from the API (403 missing scope, 404, 429 rate limit) are returned as tool errors with the API's code/message, so the agent can react instead of the connection dropping.