External Agents — Getting Started

An external agent is a server-side AI agent you build and host that connects to your ChatDrift team. It can read conversations, reply to customers, and manage tickets — 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 inbox and triages on its own schedule, a Slack bot backed by ChatDrift data, or any custom business logic that needs to act on your support data.

How it works

1. You create an External Agent record in your ChatDrift dashboard and give it a name.
2. ChatDrift generates an API key scoped to that agent.
3. Your server connects to POST /external-agent/mcp on chatdrift.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 ChatDrift dashboard, open the Team Management page. You must be a team owner or admin.
2. Click Invite Agent and choose the External Agent tab.
3. Enter a name (for example, Triage Bot or Support Automation) and a description of what the agent is allowed to operate.
4. Click Create API Key.

The agent appears on the Agents tab of the Team Management page.

Step 2 — Copy the API key

When the external agent is created, a Configuration panel on the Agents tab shows its API key together with the MCP URL. 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.

CHATDRIFT_AGENT_KEY=nex_ext_...

To issue a new key later, use the rotate button in the agent's row on the Agents tab. The revoke button disables the agent immediately.

Step 3 — Make your first MCP call

The external agent endpoint uses Streamable HTTP transport as defined in MCP 2025-11-25.

Endpoint

POST https://chatdrift.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. It does not require authentication:

curl https://chatdrift.com/external-agent/mcp

{
  "status": "online",
  "message": "Nexvio External Agent MCP Server is active",
  "endpoints": {
    "streamableHttp": "/external-agent/mcp"
  },
  "protocolVersion": "2025-11-25",
  "transport": "streamable-http"
}

List available tools

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

curl -X POST https://chatdrift.com/external-agent/mcp \
  -H "Authorization: Bearer $CHATDRIFT_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://chatdrift.com/external-agent/mcp \
  -H "Authorization: Bearer $CHATDRIFT_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://chatdrift.com/external-agent/mcp \
  -H "Authorization: Bearer $CHATDRIFT_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://chatdrift.com/external-agent/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${process.env.CHATDRIFT_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 9 tools across conversations and tickets. See the Tool Reference for the full input/output schema of each tool.