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

# MCP Server

> Connect AI assistants to your AGO workspace via Model Context Protocol

AGO exposes an MCP server at `/api/v1/mcp` with 66 tools. Most mirror the [Public API v1](/api/public-api-v1) endpoints; a few are MCP-only. Connect Claude Desktop, Claude Code, Cursor, or any MCP-compatible client and manage your workspace through natural language.

The server uses the same `X-API-Key` authentication as the REST API. Tools returned by `tools/list` are filtered based on the scopes assigned to your API key. See [API Key Authentication](/security/api-key-authentication) for creating keys and assigning scopes.

## Client Configuration

### Claude Desktop

Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "ago": {
      "url": "https://your-tenant-id.api.useago.com/api/v1/mcp",
      "headers": {
        "X-API-Key": "ago_v1_sk_your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash theme={null}
claude mcp add --transport http ago https://your-tenant-id.api.useago.com/api/v1/mcp \
  --header "X-API-Key: ago_v1_sk_your_key_here"
```

### Cursor

Add this to `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "ago": {
      "url": "https://your-tenant-id.api.useago.com/api/v1/mcp",
      "headers": {
        "X-API-Key": "ago_v1_sk_your_key_here"
      }
    }
  }
}
```

Replace `your-tenant-id` with your AGO tenant identifier.

***

## Tool Catalog

All 66 tools are listed below. Most map to a REST API endpoint (except the MCP-only tools noted below). Parameters match the auto-generated endpoint pages in the **Endpoints** sidebar section.

### Knowledge - Documents

**Scope:** `knowledge:read` / `knowledge:write`

| Tool                          | Description                                  |
| ----------------------------- | -------------------------------------------- |
| `list_documents`              | List documents with pagination and filtering |
| `get_document`                | Get a document by ID with full content       |
| `create_document`             | Create a new document                        |
| `update_document`             | Update a document                            |
| `delete_document`             | Delete a document                            |
| `bulk_create_documents`       | Create up to 100 documents in a single call  |
| `bulk_delete_documents`       | Delete up to 100 documents in a single call  |
| `list_document_translations`  | List translations for a document             |
| `create_document_translation` | Add a translation to a document              |
| `list_document_versions`      | List version history for a document          |
| `restore_document_version`    | Restore a document to a previous version     |
| `move_document`               | Move a document in the table of contents     |

### Knowledge - Sources

**Scope:** `knowledge:read` / `knowledge:write`

| Tool                      | Description                                                      |
| ------------------------- | ---------------------------------------------------------------- |
| `list_sources`            | List all knowledge sources                                       |
| `get_source`              | Get a source by ID                                               |
| `create_source`           | Create a new knowledge source                                    |
| `update_source`           | Update a knowledge source                                        |
| `delete_source`           | Delete a knowledge source                                        |
| `sync_source`             | Trigger an import or sync for a source                           |
| `get_source_sync_history` | Get the sync history for a source                                |
| `get_source_toc`          | Get the table of contents for a source                           |
| `upload_source_file`      | Upload a file (base64 encoded, max 20 MB, extracted to Markdown) |

### Knowledge - Update Requests

**Scope:** `knowledge:read` / `knowledge:write`

Knowledge update requests are detected knowledge-base gaps: questions the agent could not answer well. Use these tools to review and triage them.

| Tool                                           | Description                                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------ |
| `list_knowledge_update_requests`               | List gaps, filterable by status, source, agent, and date range                       |
| `get_knowledge_update_request`                 | Get one gap by ID, including recommended actions                                     |
| `update_knowledge_update_request_status`       | Set the review status (pending, in\_progress, resolved, rejected) and optional notes |
| `resolve_knowledge_update_request`             | Mark a gap as resolved                                                               |
| `generate_knowledge_update_request_kb_actions` | Generate recommended knowledge-base actions for a gap (runs in the background)       |

### Conversations

**Scope:** `conversations:read`

| Tool                         | Description                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `list_conversations`         | List conversations with pagination and filtering                                     |
| `get_conversation`           | Get a conversation by ID                                                             |
| `list_conversation_messages` | List messages in a conversation, including the cited knowledge documents (`sources`) |
| `list_message_feedback`      | List feedback for a specific message                                                 |
| `list_conversation_feedback` | List all feedback in a conversation                                                  |
| `list_feedback`              | Search feedback globally with filters (MCP only)                                     |
| `search_conversations`       | Full-text search on message content (MCP only)                                       |

### Tickets

**Scope:** `tickets:read`

| Tool                   | Description                                |
| ---------------------- | ------------------------------------------ |
| `list_tickets`         | List tickets with pagination and filtering |
| `get_ticket`           | Get a ticket by ID                         |
| `list_ticket_messages` | List messages in a ticket                  |
| `list_ticket_statuses` | List available ticket statuses             |
| `get_ticket_stats`     | Get ticket statistics                      |

### Analytics

**Scope:** `analytics:read`

| Tool                       | Description                                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `get_dashboard_analytics`  | Get dashboard data with date range and tab filtering                                                                       |
| `get_top_shared_documents` | List the top N documents shared in conversations over a period (by usage or clicks; defaults to last 7 days, 50 documents) |

### Agents

**Scope:** `agents_config:read` / `agents_config:write`

| Tool           | Description                          |
| -------------- | ------------------------------------ |
| `list_agents`  | List all agents                      |
| `get_agent`    | Get an agent with full configuration |
| `create_agent` | Create a new agent                   |
| `update_agent` | Update an agent                      |
| `delete_agent` | Delete an agent                      |

### Tools

**Scope:** `agents_config:read` / `agents_config:write`

| Tool              | Description               |
| ----------------- | ------------------------- |
| `list_tools`      | List all tools            |
| `get_tool`        | Get a tool by ID          |
| `create_tool`     | Create a new tool         |
| `update_tool`     | Update a tool             |
| `delete_tool`     | Delete a tool             |
| `list_tool_types` | List available tool types |

### Prompt Templates

**Scope:** `agents_config:read` / `agents_config:write`

| Tool                     | Description                  |
| ------------------------ | ---------------------------- |
| `list_prompt_templates`  | List all prompt templates    |
| `get_prompt_template`    | Get a prompt template by ID  |
| `create_prompt_template` | Create a new prompt template |
| `update_prompt_template` | Update a prompt template     |
| `delete_prompt_template` | Delete a prompt template     |

### UI Resource Templates

**Scope:** `agents_config:read` / `agents_config:write`

| Tool                          | Description                       |
| ----------------------------- | --------------------------------- |
| `list_ui_resource_templates`  | List all UI resource templates    |
| `get_ui_resource_template`    | Get a UI resource template by ID  |
| `create_ui_resource_template` | Create a new UI resource template |
| `update_ui_resource_template` | Update a UI resource template     |
| `delete_ui_resource_template` | Delete a UI resource template     |

### Organizations

**Scope:** `accounts:read`

| Tool                              | Description                                  |
| --------------------------------- | -------------------------------------------- |
| `list_organizations`              | List all organizations                       |
| `get_organization`                | Get an organization by ID with email domains |
| `list_organization_email_domains` | List email domains for an organization       |

### Users

**Scope:** `accounts:read`

| Tool         | Description      |
| ------------ | ---------------- |
| `list_users` | List all users   |
| `get_user`   | Get a user by ID |

***

## MCP-Only Tools

Two tools are available through MCP but do not have REST endpoints:

### search\_conversations

Full-text search on message content. Returns threads containing messages that match the query.

| Parameter    | Type    | Required | Description                                                                         |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------------- |
| `query`      | string  | yes      | Search keyword to match against message content                                     |
| `page`       | integer | no       | Page number                                                                         |
| `page_size`  | integer | no       | Items per page                                                                      |
| `start_date` | string  | no       | Filter from date (ISO 8601)                                                         |
| `end_date`   | string  | no       | Filter to date (ISO 8601)                                                           |
| `agent`      | string  | no       | Filter by agent UUID or name (case-insensitive). Comma-separate for multiple agents |

### list\_feedback

List all feedback across all conversations with filtering. Eliminates the need to query feedback per-thread.

| Parameter               | Type    | Required | Description                                                                         |
| ----------------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| `page`                  | integer | no       | Page number                                                                         |
| `page_size`             | integer | no       | Items per page                                                                      |
| `thread_id`             | string  | no       | Filter by thread                                                                    |
| `email`                 | string  | no       | Filter by user email                                                                |
| `start_date`            | string  | no       | Filter from date (ISO 8601)                                                         |
| `end_date`              | string  | no       | Filter to date (ISO 8601)                                                           |
| `inaccurate`            | boolean | no       | Filter for inaccurate feedback                                                      |
| `incomplete`            | boolean | no       | Filter for incomplete feedback                                                      |
| `information_not_found` | boolean | no       | Filter for information-not-found feedback                                           |
| `technical_issue`       | boolean | no       | Filter for technical issue feedback                                                 |
| `agent`                 | string  | no       | Filter by agent UUID or name (case-insensitive). Comma-separate for multiple agents |

<Note>
  Issue type filters use OR logic: setting multiple to `true` returns feedback matching **any** of the selected types.
</Note>

<Note>
  `list_conversations`, `search_conversations`, `list_feedback`, and `list_tickets` all accept an `agent` filter. For conversations, search, and feedback, pass an agent UUID or name (exact, case-insensitive), or a comma-separated list to match several agents. `list_tickets` accepts a single agent name only (case-insensitive substring match) — it does not accept a UUID or a comma-separated list. Use `list_agents` to find valid agent names. The filter narrows within your current scope and grants no additional access.
</Note>

***

## Protocol

The MCP server implements JSON-RPC 2.0 over HTTP, following the [MCP specification](https://spec.modelcontextprotocol.io/).

### Session Lifecycle

1. **Initialize** -- Send an `initialize` request with your client info and protocol version. The server responds with its capabilities and a `Mcp-Session-Id` header.
2. **Initialized** -- Send an `initialized` notification to confirm. The server responds with `202`.
3. **Use tools** -- Call `tools/list` to discover available tools, then `tools/call` to invoke them. Include the `Mcp-Session-Id` header on every request.
4. **Terminate** -- Send a `DELETE` request to end the session.

### Headers

Include these headers on every request after initialization:

| Header           | Value                                   |
| ---------------- | --------------------------------------- |
| `Content-Type`   | `application/json`                      |
| `X-API-Key`      | Your API key                            |
| `Mcp-Session-Id` | Session ID from the initialize response |

### Error Codes

| Code     | Meaning                                                  |
| -------- | -------------------------------------------------------- |
| `-32700` | Parse error -- invalid JSON                              |
| `-32600` | Invalid request -- malformed JSON-RPC or missing session |
| `-32601` | Method not found or unknown tool name                    |
| `-32602` | Invalid parameters                                       |
| `-32603` | Internal error                                           |

***

## Example: curl Session

**Step 1 -- Initialize:**

```bash theme={null}
curl -s -D - https://your-tenant-id.api.useago.com/api/v1/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": "curl-example", "version": "1.0.0"}
    }
  }'
```

Save the `Mcp-Session-Id` header from the response.

**Step 2 -- Confirm initialization:**

```bash theme={null}
curl -s https://your-tenant-id.api.useago.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ago_v1_sk_your_key_here" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "initialized"}'
```

**Step 3 -- List tools:**

```bash theme={null}
curl -s https://your-tenant-id.api.useago.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ago_v1_sk_your_key_here" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}'
```

**Step 4 -- Call a tool:**

```bash theme={null}
curl -s https://your-tenant-id.api.useago.com/api/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ago_v1_sk_your_key_here" \
  -H "Mcp-Session-Id: SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {"name": "list_documents", "arguments": {"page": 1, "page_size": 10}}
  }'
```

Tool responses wrap the data in a `content` array:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "{\"object\":\"list\",\"data\":[...],\"has_more\":true,\"total\":42}"}]
  }
}
```

**Step 5 -- End session:**

```bash theme={null}
curl -s -X DELETE https://your-tenant-id.api.useago.com/api/v1/mcp \
  -H "X-API-Key: ago_v1_sk_your_key_here" \
  -H "Mcp-Session-Id: SESSION_ID"
```

***

## Related

* [Public API v1](/api/public-api-v1)
* [API Key Authentication](/security/api-key-authentication)
* [SDK API](/api/sdk-api)