For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

The knowledge bases MCP endpoint (https://kbaas.do-ai.run/v1/mcp) provides a standardized way for AI assistants and applications to search and retrieve information from knowledge bases. It uses Streamable HTTP transport in stateless mode and supports protocol versions 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05.

Authentication and Transport

All requests to the knowledge bases MCP endpoint require authentication and MCP-compatible HTTP headers.

• Authorization: Bearer <DO_API_TOKEN> is required. Use a DigitalOcean API token with genai_read permission (GenAI:read scope).
• Requests use POST only.
• Content-Type must be application/json.
• Accept must include both application/json and text/event-stream.
• Mcp-Protocol-Version is optional and defaults to 2025-03-26.

Supported Tools

The knowledge bases MCP endpoint supports the following tools for searching and retrieving content from your knowledge bases.

retrieve_knowledge_base

Search a DigitalOcean knowledge base using hybrid semantic and keyword search. This tool is read-only, idempotent, and bounded to the selected knowledge base.

This tool takes the following arguments:

• knowledge_base_id (string, required): UUID of the knowledge base to search
• query (string, required): Search query text
• num_results (integer, required): Number of results to return, from 1 to 25
• alpha (number, optional, default: 0.5): Controls the balance between keyword and semantic search, where 0 is pure keyword search, 0.5 is balanced hybrid search, and 1 is pure semantic search.
• filters (object, optional): Metadata filters to narrow results

Filters

The filters parameter supports nested comparison and logical operators.

The filters parameter supports the following comparison operators:

• equals
• not_equals
• greater_than
• greater_than_or_equals
• less_than
• less_than_or_equals
• starts_with

The filters parameter supports the following logical operators:

• and_all
• or_all

You can’t use both and_all and or_all at the same nesting level.

Example filters

Simple equality filter:

{
  "equals": {
    "key": "category",
    "value": "documentation"
  }
}

Numeric comparison:

{
  "greater_than": {
    "key": "version",
    "value": 2.0
  }
}

Combined filters with AND:

{
  "and_all": [
    { "equals": { "key": "type", "value": "api" } },
    { "starts_with": { "key": "path", "value": "/v2/" } }
  ]
}

Combined filters with OR:

{
  "or_all": [
    { "equals": { "key": "region", "value": "us-east" } },
    { "equals": { "key": "region", "value": "us-west" } }
  ]
}

Example Usage

The following examples show how to initialize an MCP session, list the available tools, and call the retrieve_knowledge_base tool.

First, initialize the MCP session before listing tools or calling a tool:

curl -X POST "https://kbaas.do-ai.run/v1/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $DO_API_TOKEN" \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "curl-client",
      "version": "1.0.0"
    }
  }
}'

After initializing the session, list the available tools to confirm which tools the endpoint supports:

curl -X POST "https://kbaas.do-ai.run/v1/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $DO_API_TOKEN" \
-d '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}'

After initializing the session, call the retrieve_knowledge_base tool with a knowledge base ID, query, and number of results to retrieve:

curl -X POST "https://kbaas.do-ai.run/v1/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $DO_API_TOKEN" \
-d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "retrieve_knowledge_base",
    "arguments": {
      "knowledge_base_id": "123e4567-e89b-12d3-a456-426614174000",
      "query": "How do I configure authentication?",
      "num_results": 5
    }
  }
}'

The tool returns both human-readable text content and structured data. The MCP endpoint returns up to 25 results per request. For example:

{
  "total_results": 3,
  "results": [
    {
      "text_content": "Document chunk text content...",
      "metadata": {
        "source": "guide.pdf",
        "page": 5
      }
    },
    {
      "text_content": "Another document chunk...",
      "metadata": {
        "source": "api-docs.md",
        "section": "authentication"
      }
    }
  ]
}

Error Handling

Errors are returned as MCP tool results with isError: true and a descriptive message. Common error cases include authentication failures, invalid input, embedding failures, and missing or still-processing indexes.