Connect AGO to MCP Clients

Integrate AGO with Claude Desktop, Cursor, or any MCP-compatible client using the streamable HTTP transport

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools over a structured API. AGO exposes an MCP-compatible endpoint so tools like Claude Desktop, Cursor, or any standard MCP client can read your knowledge base, query conversations, pull analytics, and manage agent configuration — all through your existing AGO instance.

Prerequisites

• An AGO instance with API access enabled
• An API key with the scopes you need (see Available Tools below)
• Your AGO instance URL (e.g., https://your-org.ago.ai)

Generate an API Key

1. Go to Administration > API Keys
2. Click Create API Key
3. Give it a descriptive name (e.g., Claude Desktop MCP)
4. Select the scopes that match the tools you want to expose — for example, knowledge:read to let the client search documents, or analytics:read for dashboard data
5. Copy the key (it starts with ago_v1_sk_). You will not be able to see it again.

Connect Step by Step

AGO’s MCP endpoint uses JSON-RPC 2.0 over HTTP at /api/mcp. A session goes through these stages: initialize, list tools, call tools, and (optionally) close.

1. Initialize a Session

   Send an initialize request to get a session ID:

   curl -X POST https://your-org.ago.ai/api/mcp \
     -H "Content-Type: application/json" \
     -H "X-API-Key: ago_v1_sk_your_key_here" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
         "protocolVersion": "2025-06-18",
         "capabilities": {},
         "clientInfo": {
           "name": "my-client",
           "version": "1.0.0"
         }
       }
     }' -v
   

   The response includes the server’s capabilities and a Mcp-Session-Id header:

   < Mcp-Session-Id: abc123-session-id
   

   {
     "jsonrpc": "2.0",
     "id": 1,
     "result": {
       "protocolVersion": "2025-06-18",
       "capabilities": {
         "tools": { "listChanged": false }
       },
       "serverInfo": {
         "name": "ago-mcp-server",
         "version": "1.0.0"
       }
     }
   }
   

   Save the Mcp-Session-Id value — you need it for all subsequent requests.

2. Send the Initialized Notification

   After initialization, confirm the session is ready. This is a notification (no id field), so the server responds with 202 Accepted and no body:

   curl -X POST https://your-org.ago.ai/api/mcp \
     -H "Content-Type: application/json" \
     -H "X-API-Key: ago_v1_sk_your_key_here" \
     -H "Mcp-Session-Id: abc123-session-id" \
     -d '{
       "jsonrpc": "2.0",
       "method": "notifications/initialized"
     }'
   
3. List Available Tools

   Discover which tools your API key has access to:

   curl -X POST https://your-org.ago.ai/api/mcp \
     -H "Content-Type: application/json" \
     -H "X-API-Key: ago_v1_sk_your_key_here" \
     -H "Mcp-Session-Id: abc123-session-id" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/list"
     }'
   

   The response contains an array of tool definitions with names, descriptions, and input schemas. Only tools matching your API key scopes are returned.

4. Call a Tool

   Call a tool by name. For example, to list knowledge documents:

   curl -X POST https://your-org.ago.ai/api/mcp \
     -H "Content-Type: application/json" \
     -H "X-API-Key: ago_v1_sk_your_key_here" \
     -H "Mcp-Session-Id: abc123-session-id" \
     -d '{
       "jsonrpc": "2.0",
       "id": 3,
       "method": "tools/call",
       "params": {
         "name": "list_documents",
         "arguments": {}
       }
     }'
   

   Tool responses use this format — the result is a JSON-stringified value inside a text content block:

   {
     "jsonrpc": "2.0",
     "id": 3,
     "result": {
       "content": [
         {
           "type": "text",
           "text": "[{\"id\": \"doc_1\", \"title\": \"Return Policy\", ...}]"
         }
       ]
     }
   }
   
5. Close the Session

   When you are done, terminate the session with a DELETE request:

   curl -X DELETE https://your-org.ago.ai/api/mcp \
     -H "X-API-Key: ago_v1_sk_your_key_here" \
     -H "Mcp-Session-Id: abc123-session-id"
   

Connect Claude Desktop

Claude Desktop supports MCP servers natively through its configuration file. Add your AGO instance as a streamable HTTP server.

Open (or create) your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your AGO MCP server:

{
  "mcpServers": {
    "ago": {
      "type": "streamableHttp",
      "url": "https://your-org.ago.ai/api/mcp",
      "headers": {
        "X-API-Key": "ago_v1_sk_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. Your AGO tools will appear in the tool picker when you start a new conversation.

Connect Cursor

Cursor supports MCP servers through its settings:

1. Open Settings > MCP
2. Click Add new MCP server
3. Set the transport type to streamableHttp
4. Enter the URL: https://your-org.ago.ai/api/mcp
5. Add the X-API-Key header with your API key

After saving, Cursor will discover the available tools automatically.

Available Tools

The tools exposed to your MCP client depend on the scopes assigned to your API key. Here is what each scope unlocks:

Category	Example tools	Required scopes
Knowledge documents	list_documents, get_document, create_document, update_document	knowledge:read, knowledge:write
Knowledge sources	list_knowledge_sources, get_knowledge_source	knowledge:read
Conversations	list_conversations, get_conversation	conversations:read
Tickets	list_tickets, get_ticket	tickets:read
Analytics	get_analytics_summary, get_conversation_metrics	analytics:read
Agents configuration	list_agents, get_agent, update_agent	agents_config:read, agents_config:write
Prompt templates	list_prompt_templates, get_prompt_template	agents_config:read, agents_config:write
UI resource templates	list_ui_resource_templates, get_ui_resource_template	agents_config:read, agents_config:write

Tip: Start with read-only scopes. You can always create a second API key with write scopes later if needed.

SSE Streaming

For long-running tool calls, you can open an SSE (Server-Sent Events) stream to receive results asynchronously:

curl -N https://your-org.ago.ai/api/mcp \
  -H "X-API-Key: ago_v1_sk_your_key_here" \
  -H "Mcp-Session-Id: abc123-session-id"

The server sends a heartbeat event every 30 seconds to keep the connection alive. Standard MCP clients handle this automatically — you only need to manage SSE if you are building a custom integration.

Error Handling

Common Errors

401 Unauthorized — missing or invalid API key

Check that your X-API-Key header is present and the key starts with ago_v1_sk_.

JSON-RPC error -32600 (Invalid Request) — insufficient scope

Your API key does not have the scope required for the tool you tried to call. Generate a new key with the correct scopes, or add scopes to an existing key in Administration > API Keys.

JSON-RPC error -32601 (Method not found)

The MCP method you called does not exist. Supported methods: initialize, notifications/initialized, tools/list, tools/call, ping.

JSON-RPC error -32602 (Invalid params)

A required parameter is missing or has the wrong type. Check the tool’s input schema from the tools/list response.

JSON-RPC error -32700 (Parse error)

The request body is not valid JSON. Verify your Content-Type header is application/json and the body is well-formed.

404 on /api/mcp — session not found or expired

The Mcp-Session-Id header points to a session that no longer exists. Start a new session with an initialize request.

JSON-RPC Error Code Reference

Code	Meaning
-32700	Parse error — invalid JSON
-32600	Invalid request or insufficient scope
-32601	Method not found
-32602	Invalid params
-32603	Internal error

Related Resources

• API Authentication — how API keys and scopes work
• Tools — the built-in tools that agents (and MCP clients) can call
• MCP specification — the full protocol documentation