Kilo Code

Why this agent

Kilo Code is an AI coding agent available in two surfaces: a VS Code extension (marketplace) and a terminal CLI (@kilocode/cli). Both share the same MCP schema — one install snippet works for both surfaces.

Prerequisites

Either / both of:

• VS Code with the Kilo Code extension installed.
• Kilo CLI installed: npm install -g @kilocode/cli; kilo --version succeeds.
• espctl installed somewhere stable on disk.
• (Optional, for remote builds) An Aegis build server URL + MCP_AUTH_SECRET.

Install snippet (or alternative)

Kilo reads MCP servers from kilo.json (or kilo.jsonc):

Merge the mcp.espctl entry:

{
  "mcp": {
    "espctl": {
      "type": "local",
      "command": ["/path/to/espctl", "mcp", "serve"],
      "environment": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      },
      "enabled": true,
      "timeout": 5000
    }
  }
}

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.

Same snippet works for the VS Code extension and the CLI — Kilo shares the schema across both surfaces (per kilo-docs/automate/mcp/using-in-cli.md and kilo-docs/automate/mcp/using-in-kilo-code.md).

Alternative — fetch a pre-filled snippet:

Read the install://kilo-code resource.

Or use Kilo CLI’s runtime command:

kilo mcp add        # interactive — prompts for each field
kilo mcp list       # see currently registered servers

First-run verification

cd /path/to/your/esp-idf/project
kilo

In Kilo’s TUI / VS Code chat:

What espctl tools do you have?

Expected: ~40 espctl tools listed. In Kilo’s interactive TUI, you can also use /mcps to toggle servers on/off.

Troubleshooting

• kilo.json parse error on startup — check command: is an ARRAY (not a string), environment: (not env), type: "local" (or "remote" for HTTP).
• Tools listed but every call returns “auth required” — 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 HTTP transport? Set type: "remote" + url: "https://esphome.cloud/mcp/esp-idf" + headers: { "Authorization": "Bearer your-access-key" } instead.
• Tools take too long to enumerate — bump timeout (default 5000ms). Espctl’s tool enumeration is typically <1s but a slow network or warm-up may exceed default.
• Want to disable temporarily? Set "enabled": false rather than deleting the entry; Kilo will skip the server.

Tested as-of 2026-05-19

Kilo Code-specific notes

• The schema also supports "type": "remote" with url + headers — useful if you want Kilo to hit the browser-side https://esphome.cloud/mcp/esp-idf HTTP endpoint instead of running espctl locally.
• Kilo has an MCP Server Marketplace — for community-published MCP servers. espctl is currently published locally (this manual page); a marketplace entry could land later.
• The .jsonc variant allows comments — useful for documenting per-server settings inline. Both kilo.json and kilo.jsonc are accepted.