kb/MCP.md

MCP Server (Agent Integration)

The MCP server exposes kb operations as native MCP tools, so agents can search, add notes, upload files, and manage documents without shelling out to the CLI. kb_search is hybrid: dense vector embeddings (semantic similarity) fused with BM25 full-text ranking via Reciprocal Rank Fusion, so agents can ask natural-language questions and find conceptually related content even when the exact words don't match.

Start the MCP server

The compose files include a kb-mcp service alongside the engine. Set KB_MCP_API_KEY to require Bearer token auth from connecting agents:

KB_API_KEY=your-engine-key KB_MCP_API_KEY=your-agent-key \
  docker compose -f engine/compose.nvidia.yaml up -d

Or run the MCP server standalone:

docker run -d --name kb-mcp \
  -p 3000:3000 \
  -e KB_ENGINE_URL=http://your-engine-host:8000 \
  -e KB_API_KEY=your-engine-key \
  -e KB_MCP_API_KEY=your-agent-key \
  --restart unless-stopped \
  gitea.dcglab.co.uk/steve/kb/mcp:latest

MCP tools

Tool	Description
kb_search	Hybrid semantic (vector) + full-text search with tag/type filters
kb_addnote	Add a text note (queued for async ingestion)
kb_update_note	Update an existing note in place
kb_get	Get document details by ID or source path
kb_delete	Permanently delete a document by ID
kb_status	Engine health and statistics
kb_jobs	Ingestion queue status
kb_upload_start	Start a chunked file upload
kb_upload_chunk	Upload a base64-encoded file chunk
kb_upload_finish	Finish upload and submit for ingestion
kb_bulk_delete	Delete multiple documents matching a filter
kb_bulk_tags	Add/remove tags on multiple documents
kb_bulk_set_tags	Replace all tags on multiple documents

Organising with tags

Use tags to separate agent data from user documents. For example, an agent can tag all its notes with agent:mybot and filter by that tag when searching. This is a naming convention — configure it in your agent's system prompt. No special server-side enforcement is needed.

Bulk tools accept filter-based selection (by tags, doc_type, ID list, or ID range) so agents can manage thousands of documents in a single call instead of looping. A safety threshold (default 70%, configurable via engine env var KB_BULK_SAFETY_PERCENT) prevents accidental mass operations unless force: true is set.

MCP server configuration

Variable	Default	Description
KB_ENGINE_URL	http://localhost:8000	Engine API URL
KB_API_KEY	(none)	Engine API key
KB_MCP_API_KEY	(none)	Bearer token required from agents (disabled if unset)
KB_MCP_PORT	3000	Port to listen on

Connecting AI coding tools

The kb MCP server uses Streamable HTTP transport at http://your-host:3000/mcp. Below are configuration examples for popular AI coding tools.

Claude Code (CLI / Desktop / Web)

Add the server to your project or user settings:

claude mcp add kb-server --transport http http://localhost:3000/mcp

Or add it manually to .claude/settings.json (project) or ~/.claude/settings.json (global):

{
  "mcpServers": {
    "kb-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-agent-key"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to your .vscode/settings.json (workspace) or user settings:

{
  "mcp": {
    "servers": {
      "kb-server": {
        "type": "http",
        "url": "http://localhost:3000/mcp",
        "headers": {
          "Authorization": "Bearer your-agent-key"
        }
      }
    }
  }
}

Or add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "kb-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-agent-key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "kb-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-agent-key"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "kb-server": {
      "serverUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-agent-key"
      }
    }
  }
}

JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.)

Add to .junie/mcp.json in your project root, or configure via Settings > Tools > AI Assistant > MCP Servers:

{
  "servers": {
    "kb-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-agent-key"
      }
    }
  }
}