External Agents — Getting Started

An external agent is a server-side AI agent you build and host that connects to your ZyberDesk team. It can read conversations, reply to customers, manage tickets, create tasks, and handle approvals — all through a secure MCP connection authenticated with an API key.

Use external agents when you want to build custom automation that goes beyond the built-in workflow engine: a fully autonomous AI that monitors your tickets and triages them on its own schedule, an internal assistant backed by your ZyberDesk data, or any custom business logic that needs to act on your team's data.

How it works

1. You create an External Agent record in your ZyberDesk dashboard and give it a name.
2. ZyberDesk generates an API key scoped to that agent.
3. Your server connects to POST /external-agent/mcp on zyberdesk.com using the Streamable HTTP MCP transport, authenticated with the API key.
4. Your agent calls tools like list_conversations, reply_to_conversation, and create_task.

All actions are logged and attributed to the agent in your team's audit trail.

Step 1 — Create an external agent

1. In your ZyberDesk dashboard, open Agents from the sidebar.
2. Click New Agent and choose External Agent.
3. Give it a name (for example, Triage Bot or Support Automation).
4. Click Create.

The agent appears in your agent list with an API Keys tab.

Step 2 — Generate an API key

1. Open the agent you just created and go to the API Keys tab.
2. Click Generate key.
3. Copy the key — it starts with nex_ext_ and is shown only once.

Store the key in your server's environment variables. Do not expose it in client-side code or commit it to source control.

ZYBERDESK_AGENT_KEY=nex_ext_...

Step 3 — Make your first MCP call

The external agent endpoint uses Streamable HTTP transport as defined in MCP 2025-03-26.

Endpoint

POST https://zyberdesk.com/external-agent/mcp

Headers

Authorization: Bearer <your-agent-api-key>
Content-Type: application/json

Status probe

A GET to the endpoint returns a status object — useful for health checks:

curl https://zyberdesk.com/external-agent/mcp \
  -H "Authorization: Bearer $ZYBERDESK_AGENT_KEY"

{
  "status": "online",
  "protocol": "2025-03-26"
}

List available tools

Send an MCP tools/list call to discover the tools available to your agent:

curl -X POST https://zyberdesk.com/external-agent/mcp \
  -H "Authorization: Bearer $ZYBERDESK_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Step 4 — Use the tools

Example: list open conversations

curl -X POST https://zyberdesk.com/external-agent/mcp \
  -H "Authorization: Bearer $ZYBERDESK_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_conversations",
      "arguments": {
        "status": "unassigned",
        "limit": 10
      }
    }
  }'

Example: reply to a conversation

curl -X POST https://zyberdesk.com/external-agent/mcp \
  -H "Authorization: Bearer $ZYBERDESK_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "reply_to_conversation",
      "arguments": {
        "conversationId": "conv_abc123",
        "text": "Thanks for reaching out! Let me look into that for you."
      }
    }
  }'

Using an MCP client library

Rather than crafting raw JSON-RPC requests, most applications use an MCP client library.

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"

const transport = new StreamableHTTPClientTransport(
  new URL("https://zyberdesk.com/external-agent/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.ZYBERDESK_AGENT_KEY}`,
      },
    },
  },
)

const client = new Client({ name: "my-agent", version: "1.0.0" })
await client.connect(transport)

const result = await client.callTool({
  name: "list_conversations",
  arguments: { status: "unassigned", limit: 10 },
})

console.log(result.content)
await client.close()

Authentication errors

Tool reference

External agents have access to 18 tools across conversations, tickets, tasks, and approvals. See the Tool Reference for the full input/output schema of each tool.