API Overview
Understand ZyberDesk's MCP-first external API design and choose the right integration path.
API Overview
ZyberDesk 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
ZyberDesk 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.
Operator MCP (SSE)
Endpoint: GET /api/mcp/sse on zyberdesk.com
Use this when you want to connect an AI client — Claude Desktop, Cursor, or ChatGPT — so it can manage your ZyberDesk workspace using natural language. It exposes tools for agents, contacts, helpdocs, tickets, and analytics, scoped to your team.
Auth: Bearer token using a nex_ API key generated in Dashboard → Settings → API Keys, or an OAuth access token.
Transport: Server-Sent Events (SSE). See Agent MCP Server for client setup instructions.
External Agent MCP (Streamable HTTP)
Endpoint: POST /external-agent/mcp on zyberdesk.com
Use this when you are building an agent that needs to read and act on ZyberDesk data — reply to conversations, manage tickets, create tasks, or handle approvals — 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
| Operator MCP | External Agent MCP | |
|---|---|---|
| Endpoint | /api/mcp/sse | /external-agent/mcp |
| Auth | nex_ team API key or OAuth | External agent API key |
| Transport | SSE | Streamable HTTP |
| Tools | Agents, contacts, helpdocs, tickets, analytics | Conversations, tickets, tasks, approvals |
| 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
ZyberDesk 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.