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:

```bash
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:

```bash
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:

```bash
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):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`:

```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**:

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