Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Claude Code

Why this agent

Claude Code is Anthropic’s official CLI for Claude. Once espctl is wired up, you can ask Claude Code in plain English to build firmware, watch the build, and read the result — all from your terminal.

Prerequisites

  • Claude Code installed and on $PATH.
  • espctl installed somewhere stable on disk (full path needed below).
  • (Optional, for remote builds) An Aegis build server URL + an MCP_AUTH_SECRET access key.

Install snippet (or alternative)

Add an espctl entry under mcpServers in .claude/settings.json. Use the per-project file (<project>/.claude/settings.json, kept in your repo) or the global file (~/.claude/settings.json).

{
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "cwd": "/path/to/your/esp-idf/project",
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

Replace:

  • /path/to/espctl — full path to the espctl program on your computer.
  • /path/to/your/esp-idf/project — full path to the project Claude should work on.
  • CONTROL_BASE_URL — your build server URL. Leave it (and MCP_AUTH_SECRET) out to run in plan-only mode.
  • MCP_AUTH_SECRET — your access key from the build server. Treat it like a password; don’t put it in a public repo. If you check your .claude/settings.json into version control, remove the MCP_AUTH_SECRET line first or add the file to .gitignore.

Alternative — fetch a pre-filled snippet from any already-wired AI tool:

Read the install://claude-code resource and show me the JSON.

First-run verification

Restart Claude Code (/exit, then re-open). Then ask:

What espctl tools do you have?

Expected: a list of ~40 tools (build, doctor, store_versions, project.init, …).

Troubleshooting

  • “no tools” or “espctl failed to start” → run espctl mcp serve in a terminal yourself; the error there points at the cause (missing binary, bad cwd, etc.).
  • 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.
  • Per-project config not picked up → Claude Code reads <project>/.claude/settings.json only when you start it from inside the project directory. Run cd <project> && claude rather than pointing at the project from outside.

For a deeper checklist see Troubleshooting.

Tested as-of 2026-05-19

Per-project vs global config

WhereWhen to use
<project>/.claude/settings.jsonMost ESP-IDF projects. The path and chip target are project-specific. Check the file in (without the access key!) so collaborators get the same setup.
~/.claude/settings.jsonWhen you only have one ESP-IDF project, or you want espctl available everywhere by default.

A common pattern: keep the espctl path and CONTROL_BASE_URL in the global file, and just override cwd per project.

What to ask Claude next

  • “Run doctor” — quick health check.
  • “Initialize an esp32s3 project here” — sets up a new project.
  • “Build the project for esp32s3 and tell me if anything breaks” — builds and reports back.

See Typical Workflow for a longer example.