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 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 for creating keys and assigning scopes.

Client Configuration

Claude Desktop

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

{
  "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

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:

{
  "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

Issue type filters use OR logic: setting multiple to true returns feedback matching any of the selected types.

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.

---

Protocol

The MCP server implements JSON-RPC 2.0 over HTTP, following the MCP specification.

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:

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:

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:

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:

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:

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

Step 5 — End session:

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 Key Authentication
• SDK API