> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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.

<Steps>
  <Step title="Initialize a Session">
    Send an `initialize` request to get a session ID:

    ```bash theme={null}
    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:

    ```text theme={null}
    < Mcp-Session-Id: abc123-session-id
    ```

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="List Available Tools">
    Discover which tools your API key has access to:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Call a Tool">
    Call a tool by name. For example, to list knowledge documents:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 3,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "[{\"id\": \"doc_1\", \"title\": \"Return Policy\", ...}]"
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Close the Session">
    When you are done, terminate the session with a DELETE request:

    ```bash theme={null}
    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"
    ```
  </Step>
</Steps>

## 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:

```json theme={null}
{
  "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:

```bash theme={null}
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](/security/authentication) — how API keys and scopes work
* [Tools](/features/tools) — the built-in tools that agents (and MCP clients) can call
* [MCP specification](https://modelcontextprotocol.io/) — the full protocol documentation