Skip to main content

​
Tools

ToolPurpose
kb_search(query, top_k?, scope_prefix?)Semantic search; returns chunks with kh-id citations.
kb_fetch(kh_id)Full document content + frontmatter for a stable kh-id.
kb_list_scope(prefix?)List nodes under a scope prefix; omit for the full tree.
kb_node(kh_id)Single node plus 1-hop neighbours (related, derived_from).
The server is read-only by design. Writes go through the Cerebrum admin UI (humans) or the worker’s diary writer (agents).

​
Transport

Selected at runtime by KB_MCP_TRANSPORT. The same binary handles all three:
ValueWhen to use
stdio (default)Local clients — Claude Desktop, claude mcp add. The client execs the binary; stdio is the wire.
streamable-httpThe in-cluster deployment and any partner-tier endpoint. Spec-current MCP transport.
sseOlder HTTP clients that don’t yet speak streamable-http.
HTTP modes bind to KB_MCP_BIND_HOST:KB_MCP_BIND_PORT (default 0.0.0.0:8080). When KB_MCP_AUTH_TOKEN is set, every HTTP request must carry Authorization: Bearer <token> — enforced by Starlette middleware with constant-time comparison. Leaving the token unset is correct for cluster-internal-only deployments where NetworkPolicy or ingress owns the trust boundary.

​
Configuration

VariableRequiredDefaultNotes
KB_MCP_TRANSPORTnostdiostdio | streamable-http | sse. Aliases http and streamable_http accepted.
KB_MCP_BIND_HOSTHTTP only0.0.0.0uvicorn host.
KB_MCP_BIND_PORTHTTP only8080uvicorn port.
KB_MCP_AUTH_TOKENHTTP recommended—Bearer token required on /mcp requests when set.
MOTHER_AI_URLyes—Cerebrum Mother AI endpoint.
MOTHER_AI_API_KEYdepends—Required when Mother AI has it set.
KB_MCP_ACTORnomcp:local (stdio) / mcp:cluster (HTTP)Per-client identifier in audit rows.
KB_MCP_TIMEOUT_Sno20Upstream HTTP timeout.
KB_MCP_LOG_LEVELnoINFOstderr only on stdio; stdout is reserved for the wire.

​
Cluster deployment

The cerebrum-mcp Terraform module (terraform/modules/cerebrum-mcp/) ships a Deployment + ClusterIP Service. Workers and other in-cluster tooling reach it at: 
http://cerebrum-mcp.cerebrum.svc.cluster.local/mcp
A public ingress is templated but gated by mcp_public_enabled (default off). When enabled it attaches to the existing ingress-nginx with per-IP rate limiting; the auth token is enforced by the server middleware, not the ingress, so token rotation only touches the K8s Secret.

​
Local install (stdio)

cd mcp/cerebrum-kb
pip install -e .
Wire into Claude Desktop via claude_desktop_config.json, or via Claude Code: 
claude mcp add cerebrum-kb --command cerebrum-kb-mcp

​
Invariants

  • stdout is reserved for the MCP wire protocol on stdio transport. All logs go to stderr.
  • The server is stateless beyond its HTTP client. Audit rows, search index, and tier rules all live in Mother AI / Qdrant / Postgres.
  • Errors from Mother AI (auth, rate limit, tier-denied) flow through unchanged so the client can surface them to the user.
  • Auth checks use constant-time comparison. No token-length oracle to unauthenticated callers.