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.

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 \
  docker.dcglab.co.uk/dcg/kb/mcp:latest

MCP tools

Tool	Description
kb_search	Hybrid search with optional collection/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_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

Collections

The MCP server supports collections — scoped document namespaces implemented via tag conventions. Use these to separate agent memory from user documents:

• documents (default) — user-facing documents
• memory — agent memory and preferences
• workspace — working context

Tools accept a collection parameter. The MCP server translates this to collection:<name> tags on the engine, and strips them from responses so agents see a clean "collection": "memory" field.

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