Knowledge MCP

Agents use the organization’s knowledge base through MCP (ADR-0005: Knowledge as a Separate Service with an MCP Interface): streamable HTTP at /mcp on the Knowledge service.

Authentication

Authorization: Bearer <run token> with audience knowledge. The token’s organization selects the knowledge space; knowledge.read allows the read tools, knowledge.write the write tools. Requests without a valid token get 401; tool calls outside the token’s capabilities fail with a tool error. Entries are recorded with the run’s subject as author.

Configuring an agent

For Claude Code (.mcp.json in the run’s workspace — the agent writes it):

{"mcpServers": {"ballet-knowledge": {
   "type": "http", "url": "http://knowledge:8081/mcp",
   "headers": {"Authorization": "Bearer ${BALLET_RUN_TOKEN}"}}}}

Tools

Tool	Input	Result
knowledge_search	query; kind, project, limit (default 10)	entries: summaries (id, kind, title, snippet, projects, items, version, score), best first — hybrid full-text and semantic search
knowledge_list	kind, project, item (e.g. WEB-42), limit (default 50)	entries, most recently updated first
knowledge_get	id	The full entry with body (Markdown), updated_by, updated_at
knowledge_create	kind (document, decision, note, debt), title; body, projects (default: the run’s project), items	The created entry
knowledge_update	id, version (as read); any of kind, title, body, projects, items	The updated entry; a stale version is rejected, previous versions are kept

Trying it

TOKEN=$(bin/devtoken -keys data/token-keys.json -organization acme -project WEB \
  -ticket WEB-1 -aud knowledge -caps knowledge.read,knowledge.write)
curl localhost:8081/mcp -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"knowledge_search","arguments":{"query":"invoice export"}}}'