Skip to content

MCP Configuration for BrainLayer

One MCP server: BrainBar on /tmp/brainbar.sock. Agents connect with the shipped reconnecting brainlayer-mcp-stdio-bridge (no Homebrew socat required; GUI hosts like Zed/VS Code/Claude Desktop do not have /opt/homebrew/bin on PATH). socat STDIO UNIX-CONNECT:/tmp/brainbar.sock exits when BrainBar restarts and leaves persistent clients with a closed transport. The Python brainlayer-mcp entrypoint is deleted — do not wire it.

Prerequisites:

  • BrainBar is running and owns /tmp/brainbar.sock.
  • brainlayer-mcp-stdio-bridge is installed at the stable Homebrew opt path (use /usr/local/opt/brainlayer/bin/brainlayer-mcp-stdio-bridge on Intel).

Add this to Claude, Codex, Cursor, or Gemini MCP settings under mcpServers:

{
  "mcpServers": {
    "brainlayer": {
      "command": "/opt/homebrew/opt/brainlayer/bin/brainlayer-mcp-stdio-bridge"
    }
  }
}

Legacy raw-socket form (doctor reports its restart risk; migrate persistent agent clients):

{
  "mcpServers": {
    "brainlayer": {
      "command": "socat",
      "args": ["STDIO", "UNIX-CONNECT:/tmp/brainbar.sock"]
    }
  }
}

brainlayer setup --migrate-mcp backs up and upgrades owned legacy and raw-socat entries to the absolute opt-path bridge shown above. Verification executes that same path. Setup refuses migration if the opt bridge is missing or does not resolve to an executable inside the BrainLayer keg; install it with Homebrew first. It preserves timeouts, disabled state, unrelated servers, and other environment variables. For entries converted from socat, it removes MCPLAYER_BRAINLAYER_FRONT: socat ignored that variable, but the bridge would use it to switch the entry from direct BrainBar access to the mcplayer proxy. The original variable remains in the backup. Existing bridge entries keep their environment and route. Doctor reports an explicit proxy route as info, and reports bare, version-pinned or foreign bridge targets with their resolved paths. Project .mcp.json can override the base Codex config, so those owned files are included. A thread whose transport has already closed needs a fresh MCP connection or session.

Testing the MCP Server

  1. Confirm BrainBar owns the MCP socket:

    test -S /tmp/brainbar.sock
    (printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n'; sleep 1) \
      | socat STDIO UNIX-CONNECT:/tmp/brainbar.sock \
      | tee /tmp/brainlayer-mcp-smoke.out
    grep '"id":1' /tmp/brainlayer-mcp-smoke.out
    

  2. In Claude Code, the core palette should appear — 5 tools, not all 16:

  3. brain_search - Search memory by topic
  4. brain_store - Persist decisions, corrections, learnings
  5. brain_recall - Session context and stats
  6. brain_expand - Open one search result in full, with surrounding chunks
  7. expand_palette - Expose the other 12 tools for this session

Calling expand_palette (or starting the server with BRAINLAYER_MCP_PROFILE=full) returns all 16 with their full descriptions. A gated tool called before expanding returns an error saying so.

Migrated socat entries retain a non-default UNIX-CONNECT target through BRAINLAYER_MCP_SOCKET. If an existing socket override conflicts with that target, setup skips the entry and doctor names both targets.