Crush

Why this agent

Crush is Charm’s glamorous open-source terminal AI coding agent, with multi-model support, LSP integration, and first-class MCP support via three transport flavours (stdio / http / sse).

Prerequisites

• Crush installed: brew install charmbracelet/tap/crush, npm install -g @charmland/crush, or one of the other supported package managers. crush --version succeeds.
• espctl installed somewhere stable on disk (full path needed below).
• (Optional, for remote builds) An Aegis build server URL + MCP_AUTH_SECRET.

Install snippet (or alternative)

Crush reads MCP servers from a crush.json config file — either in your project root (./crush.json) or globally (~/.config/crush/crush.json). Merge the mcp.espctl entry:

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "espctl": {
      "type": "stdio",
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      },
      "timeout": 120,
      "disabled": false
    }
  }
}

Replace:

• /path/to/espctl — full path to the espctl program on your computer.
• CONTROL_BASE_URL — your Aegis build server URL.
• MCP_AUTH_SECRET — your access key from the build server.

Crush supports shell-style expansion in values: you can substitute "$MCP_AUTH_SECRET" (env-var lookup) or "$(cat ~/.aegis/token)" (command substitution) instead of pasting the literal token.

Alternative — fetch a pre-filled snippet:

Read the install://crush resource.

First-run verification

Restart Crush (crush will load the new config on next launch). Then in any session:

What espctl tools can you call?

Expected: a list of ~40 espctl tools.

Troubleshooting

• crush.json parse error on startup — Crush prints the parser error on stderr. Common cause: top-level key should be mcp (NOT mcpServers — Claude-Code-style); per-server type field is required.
• Tools listed but every call returns “auth required” — your MCP_AUTH_SECRET is missing or has been revoked. Get a fresh access key from the control plane and paste it into the config.
• Want to disable temporarily? Set "disabled": true rather than deleting the entry; Crush will skip the server on next launch.
• Want to limit which espctl tools Crush sees? Set "disabled_tools": ["tool-name", ...] in the espctl entry.

Tested as-of 2026-05-19

Crush-specific notes

• Crush’s MCP transport supports HTTP and SSE in addition to stdio, which is useful if you want to point Crush at the browser-side https://esphome.cloud/mcp/esp-idf HTTP endpoint instead of running a local espctl server. Replace the snippet with:

  "espctl": {
    "type": "http",
    "url": "https://esphome.cloud/mcp/esp-idf",
    "timeout": 120,
    "disabled": false,
    "headers": {
      "Authorization": "Bearer $MCP_AUTH_SECRET"
    }
  }
  

• Crush honours shell expansion ($VAR, ${VAR:-default}, $(cmd)) in command, args, env, headers, and url. Use ${MCP_AUTH_SECRET:?set MCP_AUTH_SECRET} to fail loudly at load time if the env var is unset.