Brain MCP server

The kernel ships an MCP server — agentibrain-mcp — that exposes brain + KB retrieval tools to agents. It lives in services/mcp/ and is the canonical retrieval surface. Agents do not query Postgres, Obsidian, or the inference-gateway directly; they call these tools.

Tools (Phase 1)

Tool	Purpose
brain_search_arcs	Semantic search over arcs in clusters/. Filters by min_heat and min_score, ranked by cosine similarity.
brain_get_arc	Fetch full text + metadata for one arc by cluster_id.
kb_search	Federated retrieval across embeddings (semantic) + brain-api vault search (text). Normalised, score-ranked.
kb_brief	Runs kb_search, synthesises a 3-5 line brief via inference-gateway, returns candidate_refs ready to feed downstream.

Tool source: services/mcp/app/tools/{arcs.py,kb.py}.

kb_dispatch and kb_converse are Phase 2 — they need bundle + theme assembler packages that currently live in the upstream artifact-store MCP.

Image

ghcr.io/the-cloud-clockwork/agentibrain-mcp:dev|latest

Built from services/mcp/Dockerfile by the kernel docker-build workflow on every push to dev (→:dev) and main (→:latest).

Runtime

Dockerfile pattern: FastMCP stdio Python server wrapped by mcp-proxy (npm) for HTTP/SSE. Port 8080. /ping returns pong. /mcp is the JSON-RPC endpoint.

Required env vars:

Var	Purpose
BRAIN_API_URL	agentibrain-brain-api service base URL
KB_ROUTER_TOKEN	bearer for brain-api
EMBEDDINGS_URL	agentibrain-embeddings service base URL
EMBEDDINGS_API_KEY	bearer for embeddings — same token the kernel-internal services use
INFERENCE_URL	inference-gateway endpoint (used by kb_brief)
KB_BRIEF_ROUTE	named route in inference-gateway config
MCP_PROXY_API_KEY	bearer enforced by mcp-proxy on inbound requests

Auth is two-layered:

1. The proxy authenticates the caller (LiteLLM gateway) with MCP_PROXY_API_KEY.
2. The Python tools authenticate themselves to brain-api + embeddings with their own bearer tokens.

Install — Kubernetes

The kernel ships a first-class Helm chart at helm/mcp/. Same pattern as the other charts: depends on tcc-k8s-service-template v0.3.8, ships generic defaults, accepts a per-env values overlay.

helm dep update helm/mcp
helm install agentibrain-mcp ./helm/mcp \
  -n <your-namespace> --create-namespace \
  -f your-overlay-values.yaml

Sample ArgoCD Application CR ships at examples/argocd/dev/agentibrain-mcp.yaml.example.

Optional — bring-your-own MCP-proxy chart

If your platform already standardises on a generic mcp-proxy chart for every MCP server, the snippet below shows how to point that chart at the kernel image instead of using helm/mcp/. Skip this section if you don’t have such a chart.

spec:
  source:
    path: k8s/charts/mcp-proxy        # your generic mcp-proxy chart
    helm:
      valuesObject:
        tpl:
          fullnameOverride: mcp-agentibrain
          env:
            variables:
              BRAIN_API_URL: http://agentibrain-brain-api.<ns>.svc:8080
              EMBEDDINGS_URL: http://agentibrain-embeddings.<ns>.svc:8080
              INFERENCE_URL: http://<inference-gateway-ip>:8103
              KB_BRIEF_ROUTE: kb-brief
          app:
            image:
              repository: ghcr.io/the-cloud-clockwork/agentibrain-mcp
              tag: dev   # or latest
          secrets:
            external:
              secretName: mcps-secrets   # supplies KB_ROUTER_TOKEN, EMBEDDINGS_API_KEY, MCP_PROXY_API_KEY

Pod listens on port 8080. Expose as ClusterIP for in-cluster consumers (e.g. LiteLLM gateway).

Wiring Claude Code (laptop)

After docker compose up -d from the repo root, the MCP server listens on http://localhost:8104/mcp. Add it to Claude Code’s MCP config — typically ~/.claude/.mcp.json or your project-local .mcp.json:

{
  "mcpServers": {
    "agentibrain": {
      "url": "http://localhost:8104/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_PROXY_API_KEY}"
      }
    }
  }
}

Get the bearer value from .env (generated by local/bootstrap.sh):

grep ^MCP_PROXY_API_KEY .env

Restart Claude Code, then verify the tools are wired:

/mcp                                # lists registered MCP servers
                                    # expect "agentibrain" with 4 tools

The 4 tools (brain_search_arcs, brain_get_arc, kb_search, kb_brief) appear in your tool surface as mcp__agentibrain__<tool>.

Wiring Claude Code agent mode (Kubernetes)

For an in-cluster agent (brain-keeper, agenticore, or any agent pod that ships Claude Code with AGENT_MODE=true), point at the MCP Service URL of the chart you deployed in the previous section:

{
  "mcpServers": {
    "agentibrain": {
      "url": "http://agentibrain-mcp.<your-namespace>.svc:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_PROXY_API_KEY}"
      }
    }
  }
}

The bearer comes from the K8s Secret backing helm/mcp/values.yaml’s secrets.external.secretName (default agentibrain-mcp-secrets). Inject it via envFrom: secretRef: on the agent pod, or mount it explicitly.

Wiring through LiteLLM

Register agentibrain as an MCP server pointing at the in-cluster service URL. Bind it to the relevant unit (e.g. tools-knowledge) so agents see the tools as mcp__<unit>__agentibrain-<tool>.

GitOps path (in your litellm-state repo):

1. servers/agentibrain.json — server entry with url: http://mcp-agentibrain.<ns>:8080/mcp, transport: http, auth_type: api_key.
2. teams/<team>.json — add agentibrain to the team’s server allowlist.
3. units/<unit>.json — add agentibrain under servers and list the 4 tool names under tools.agentibrain.

Reconcile workflow handles the rest. After reconcile, restart litellm-0 once so it refreshes its in-process MCP tool cache.

Local dev

cd services/mcp
pip install -r requirements.txt
BRAIN_API_URL=http://localhost:8102 \
KB_ROUTER_TOKEN=... \
EMBEDDINGS_URL=http://localhost:18080 \
EMBEDDINGS_API_KEY=... \
python app/server.py    # stdio MCP — connect with mcp-proxy or claude --debug

Smoke tests: pytest services/mcp/tests/.