Kunkun Docs

Kunkun exposes an MCP (Model Context Protocol) server at /mcp/rag that lets MCP-compatible AI clients (Claude Code, OpenCode, Cursor) search and ask questions against your knowledge bases directly from your editor or terminal.

How it works

The MCP server runs alongside the local API server on port 9559 and shares the same authentication. It registers four tools:

Tool	Input	Description
`list_rag_instances`	—	List all accessible RAG instances
`rag_status`	`instanceId`	Get status and metadata for a knowledge base
`rag_search`	`instanceId`, `query`, optional `topK`, `mode`, `pathPrefixes`, `languages`	Search indexed content
`rag_ask`	`instanceId`, `question`, optional `topK`, `maxContextChunks`	Ask a grounded question

Prerequisites

Kunkun running with the Local API Server enabled
A valid API key with at least RAG search and ask permissions
At least one knowledge base with indexed content

Configuration

Claude Code

Add to your Claude Code MCP configuration (~/.claude/settings.json):

{
  "mcpServers": {
    "kunkun-rag": {
      "type": "url",
      "url": "http://localhost:9559/mcp/rag",
      "headers": {
        "Authorization": "Bearer kk-xxxx"
      }
    }
  }
}

OpenCode

Add to your OpenCode MCP configuration (~/.config/opencode/mcp.json):

{
  "mcpServers": {
    "kunkun-rag": {
      "type": "url",
      "url": "http://localhost:9559/mcp/rag",
      "headers": {
        "Authorization": "Bearer kk-xxxx"
      }
    }
  }
}

Replace kk-xxxx with your actual API key. Create one in Settings → API Keys if you haven't already.

Other MCP clients

Any MCP-compatible client that supports Streamable HTTP transport can connect to http://localhost:9559/mcp/rag with an Authorization: Bearer <key> header.

Usage examples

Once connected, your AI agent can use these tools automatically. Here's what you might ask:

"Search my docs knowledge base for the permission model"
→ Uses rag_search to find relevant chunks

"Look up the API reference for record storage from my indexed docs"
→ Uses rag_ask to synthesize an answer with citations

"List my knowledge bases"
→ Uses list_rag_instances

Security

The MCP endpoint sits behind the same authentication and authorization as the REST API:

Same API key scoping applies — a key with only search/ask permissions can't manage items via MCP
The server is loopback-only (127.0.0.1)
All requests are validated server-side per-request, not just at connection time

Also available as REST

Prefer plain HTTP? The same capabilities are available as REST endpoints. The MCP server is a thin wrapper that maps MCP tool calls to the same underlying handlers.

AI Search MCP