BRIX

BRIX MCP: operate BRIX from Claude Desktop, Codex or Claude Code

BRIX MCP is a local MCP server that lets Claude Desktop, the Codex app or Claude Code operate the BRIX app running on the same machine. The outside agent can list terminals, send prompts and read replies, spawn agents, create squads, write notes and tasks, and switch modes. One click registers it; the medmaestri CLI does the same from any shell.

Updated · by the BRIX team

What is the BRIX MCP server?

BRIX is a desktop app where several Claude Code and Codex agents work side by side. The BRIX MCP server lets an agent that lives outside the app drive it by command instead of clicks. Your Claude Desktop chat can tell the Claude Code inside BRIX to fix a bug, wait for it to finish and read what it did.

  • Local only. The client starts the server over stdio; it talks to the open app through a socket in ~/.brix, with a token created when the app boots. No network, no cloud relay.
  • One tool = one CLI command. Every MCP tool maps to a medmaestri command, so anything you can do from the protocol you can also do from a terminal.
  • The agent is a guest. It sees all terminals, notes, images and task lists; whatever it creates appears in the app's active Area, where you watch it happen.
  • On every plan. BRIX MCP is part of STARTER. Tools that open a marketing studio need PRO, and fail with the reason when the plan does not include it.

How do I connect Claude Desktop, Codex or Claude Code to BRIX?

  1. 1

    Install and open BRIX

    Download BRIX for macOS (Apple Silicon) or Windows and open it once. On boot the app writes the server wrapper to ~/.brix/bin/brix-mcp.

  2. 2

    Register the server

    Open the BRIX SKILLS panel and click Configure BRIX MCP (onboarding offers the same button). It writes a brix entry into every MCP client found on the machine.

  3. 3

    Restart the client

    Quit and reopen Claude Desktop or the Codex app; start a new Claude Code session. Clients only read MCP config on startup.

  4. 4

    Check the connection

    Ask the outside agent to call brix_status. It answers with the BRIX version if the app is open.

From a shell, the same registration:

~/.brix/bin/medmaestri mcp status
~/.brix/bin/medmaestri mcp install              # every client found
~/.brix/bin/medmaestri mcp install claude-desktop
~/.brix/bin/medmaestri mcp uninstall codex

The installer merges, never overwrites: your other MCP servers stay. If an existing config file is not valid JSON, it is left untouched and the client shows as "not configured". Clients that are not installed are skipped.

Where does the BRIX MCP entry go in each client config?

ClientConfig fileEntry
Claude Desktop (macOS)~/Library/Application Support/Claude/claude_desktop_config.jsonmcpServers.brix
Claude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.jsonmcpServers.brix
Codex (CLI and app)~/.codex/config.toml (or $CODEX_HOME)[mcp_servers.brix]
Claude Code~/.claude.jsonmcpServers.brix, type stdio

If you prefer to edit by hand, the entry only needs the command. For Claude Desktop or Claude Code (on Windows the wrapper is brix-mcp.cmd):

{
  "mcpServers": {
    "brix": { "command": "/Users/you/.brix/bin/brix-mcp", "args": [] }
  }
}

For Codex:

[mcp_servers.brix]
command = "/Users/you/.brix/bin/brix-mcp"
args = []

What can an outside agent do through BRIX MCP?

ToolWhat it does
brix_status / brix_openIs the app open? Opens it if not.
brix_manualExplains Areas, Grid, Canvas, Scene and modes to the agent (also the brix://manual resource).
brix_listLists terminals, notes, images and task lists by name.
brix_askSends a prompt to a terminal and waits for the answer (about 2 minutes).
brix_send / brix_wait / brix_checkTypes without waiting, waits until the terminal goes quiet, or reads its screen.
brix_spawn / brix_dismissCreates a terminal running Claude Code, Codex, OpenCode, Gemini, Antigravity or a shell, with a briefing; closes only terminals it created.
brix_team / brix_squadBuilds a supervisor plus workers, or a ready-made squad (feature, cacabug, blindagem, oferta, conteudo).
brix_connectDraws or removes the edge between two terminals — the permission for them to talk.
brix_note_* / brix_tasks_* / brix_image_addWrites notes, task lists and images on the Canvas.
brix_superagentLists, creates and opens SuperAgents with persistent memory.
brix_modeSays which mode the app is in and switches to another.
brix_ads_promptsDelivers 3 to 5 ad prompts as cards in the Static Ads PromptLab (PRO).
brix_cliEscape hatch: runs any other medmaestri command.

Safety rails are in the tools themselves: brix_ads_prompts never starts image generation (that spends your image credits and only happens when you ask), and brix_dismiss refuses to close terminals you opened.

How do I use the medmaestri CLI instead of MCP?

Every terminal inside BRIX already has medmaestri on its PATH — that is how agents on the Canvas talk to each other. From any other terminal, call the stable wrapper at ~/.brix/bin/medmaestri (medmaestri.cmd on Windows). The app must be open.

medmaestri list --all
medmaestri ask "Backend" "run the tests and summarize failures"
medmaestri send "QA" "re-test the checkout after Backend is done"
medmaestri check "QA" --clean
medmaestri squad cacabug
medmaestri mode copy
medmaestri help

Use the CLI in scripts and git hooks, or when your agent runs shell commands better than MCP tools. Use MCP when the outside client is a chat app like Claude Desktop that has no shell of its own.

What does a typical session look like?

  1. 1

    Ask from Claude Desktop

    "Create a bug-hunt squad in BRIX and put it on the coupon bug in checkout."

  2. 2

    The squad appears in BRIX

    The agent calls brix_squad cacabug: Repro, Investigator and Fixer show up in the active Area, briefed and connected.

  3. 3

    It follows up

    It sends the bug report with brix_send, then brix_wait on Fixer until the terminal goes quiet, and reads the result.

  4. 4

    It leaves a trace

    It writes a summary note on the Canvas with brix_note_create, so the result stays in the app after the chat ends.

Meanwhile you watch the terminals run in the Grid, on the Canvas or as pixel-art characters in the Scene. See how BRIX works and orchestrating a team of agents.

Frequently asked questions

Does BRIX MCP send my data to a server?

No. It runs as a local stdio process and talks to the open BRIX app through a socket in ~/.brix, protected by a token. Nothing goes over the network.

Does BRIX need to be open for the MCP server to work?

Yes. The server talks to the running app. If it is closed, the agent can call brix_open to launch it and then check with brix_status.

Which plan includes BRIX MCP?

Every plan, starting with STARTER. Tools that open the marketing studios, like brix_ads_prompts, need PRO.

Can the outside agent close or delete my terminals?

No. brix_dismiss only closes terminals the agent itself created with brix_spawn.

I configured it but Claude Desktop does not see the tools. What now?

Fully quit and reopen Claude Desktop, since it reads MCP config only at startup. Then run medmaestri mcp status to confirm the brix entry points at the wrapper.

Keep reading