API Overview
Understand ChatDrift's MCP-first external API design and choose the right integration path.
API Overview
ChatDrift uses the Model Context Protocol (MCP) for operator and external-agent integrations. It also exposes a small set of public JSON endpoints for product discovery; the widget and outbound webhooks are separate integration surfaces.
Note
ChatDrift does not offer a general-purpose JSON REST API for external consumers. The
public discovery endpoints /api/public/v1/status, /api/public/v1/plans, and
/api/public/v1/capabilities return public product information. Other dashboard
/api/* routes require a session. Use MCP for external agent and operator actions.
Two integration paths
Choose based on who or what is making the request.
Team Operator MCP (Streamable HTTP)
Endpoint: POST /api/mcp on chatdrift.com (GET /api/mcp returns status)
Use this when you want to connect an AI client — Claude Desktop, Cursor, or ChatGPT — so it can manage your ChatDrift workspace using natural language. It exposes tools for agents, contacts, helpdocs, tickets, and analytics, scoped to your team.
Auth: Bearer token using an OAuth access token (issued when you connect an AI client), or a nex_ team API key such as the published demo key described in Sandbox. The Settings → API Keys page in the dashboard manages your own AI provider keys, not keys for this endpoint.
Transport: Stateless Streamable HTTP. Send MCP JSON-RPC requests with POST; this team endpoint always returns the response as JSON (application/json). See Sandbox for the current endpoint and key, or the generated /auth.md for auth discovery.
Note
The old team SSE transport at GET /api/mcp/sse and its /api/mcp/message channel are deprecated during migration. They remain enabled by default and return Deprecation and successor Link headers; set MCP_LEGACY_SSE_ENABLED=false to close the migration gate and return 410 Gone. New clients should use POST /api/mcp.
External Agent MCP (Streamable HTTP)
Endpoint: POST /external-agent/mcp on chatdrift.com
Use this when you are building an agent that needs to read and act on ChatDrift data — reply to conversations and manage tickets on behalf of your team. It uses the newer Streamable HTTP transport and is designed for server-to-server use.
Auth: Bearer token using an external agent API key generated in Dashboard → Agents → [Your Agent] → API Keys.
Transport: Streamable HTTP (MCP 2025-03-26). See External Agents to get started.
Summary
| Team Operator MCP | External Agent MCP | |
|---|---|---|
| Endpoint | POST /api/mcp | POST /external-agent/mcp |
| Auth | nex_ team API key or OAuth | External agent API key |
| Transport | Streamable HTTP (application/json response) | Streamable HTTP |
| Tools | Agents, contacts, helpdocs, tickets, analytics | Conversations, tickets |
| Typical user | AI assistant (Claude, Cursor, ChatGPT) | Custom server-side agent you build |
| Docs | Agent MCP Server | External Agents |
Widget integration
The embeddable agent widget (@nexvio-ai/widget-js) is a separate, client-side integration that does not use MCP. It loads the widget frame in the browser and optionally verifies logged-in users with JWT or HMAC. See the Widget SDK reference.
Outbound events
ChatDrift can push events to your server when contacts, tickets, or actions change. This uses standard HTTPS webhooks with HMAC-SHA256 signatures — not MCP. See Outbound Webhooks.