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-bridgeis installed at the stable Homebrew opt path (use/usr/local/opt/brainlayer/bin/brainlayer-mcp-stdio-bridgeon 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
-
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 -
In Claude Code, the core palette should appear — 5 tools, not all 16:
brain_search- Search memory by topicbrain_store- Persist decisions, corrections, learningsbrain_recall- Session context and statsbrain_expand- Open one search result in full, with surrounding chunksexpand_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.