175 lines
4.5 KiB
Markdown
175 lines
4.5 KiB
Markdown
# 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 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:
|
|
|
|
```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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|