Cursor

Why this agent

Cursor is a code-aware IDE built on VS Code with first-class MCP support. Once espctl is wired up, Cursor’s chat panel can drive ESP-IDF builds, read logs, and flash firmware without leaving the editor.

Prerequisites

• Cursor installed (any 0.40+ release with MCP support).
• 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)

Add to .cursor/mcp.json in your workspace, or ~/.cursor/mcp.json to make espctl available across every Cursor workspace:

{
  "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"
      }
    }
  }
}

What to put in each field:

• command — full path to the espctl program.
• cwd — full path to the ESP-IDF project Cursor should work on.
• CONTROL_BASE_URL + MCP_AUTH_SECRET — leave both out for plan-only mode; set both for remote builds.

Alternative — pre-filled snippet via MCP resource:

Read the install://cursor resource.

First-run verification

Restart Cursor. Open the chat panel and ask:

What espctl tools do you have?

Expected: ~40 tools listed (build, doctor, store_versions, …).

Troubleshooting

• Tool list empty or “espctl failed to start” → check Cursor’s MCP log panel (Output → MCP). The actual error from espctl mcp serve appears there.
• Shell-set env vars not visible → if you’ve pinned Cursor to a specific shell (e.g. fish), Cursor may not inherit your ~/.zshrc/~/.bashrc exports. List every variable directly inside the env block.
• Per-workspace vs global → Cursor MCP support is workspace-level. Per-workspace .cursor/mcp.json is the most common setup.

Tested as-of 2026-05-19