OpenCode

Why this agent

OpenCode is an open-source AI coding tool with first-class MCP support. Its config shape differs from the JSON-based agents (single command array, mcp not mcpServers), but the underlying behaviour is the same.

Prerequisites

• OpenCode installed (any 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 opencode.json in your project folder, or ~/.config/opencode/opencode.json to make espctl available everywhere:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "espctl": {
      "type": "local",
      "command": ["/path/to/espctl", "mcp", "serve"],
      "enabled": true,
      "environment": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

Four things to notice compared to the JSON-based AI tools:

1. The top-level key is mcp, not mcpServers.
2. command is a single array with the program and all its arguments together, not a separate command + args.
3. The environment-variable key is environment, not env.
4. type must be "local" for a program launched on your computer (which espctl is).

The path/value rules are otherwise the same as in Claude Code.

Alternative — fetch a pre-filled snippet:

Read the install://opencode resource.

First-run verification

Restart OpenCode. In any chat:

What espctl tools can you call?

Expected: ~40 tools listed.

Troubleshooting

• Tool list empty / “espctl failed to start” → OpenCode’s logs show the actual error. Locations:
  • Linux: ~/.local/share/opencode/logs/
  • macOS: ~/Library/Logs/opencode/
• command parse error → make sure command is a JSON array (e.g. ["espctl", "mcp", "serve"]), not the JSON-string form used by other agents.
• Want to disable temporarily → set "enabled": false rather than deleting the entry; OpenCode will skip the server on its next start.

Tested as-of 2026-05-19

OpenCode-specific notes

OpenCode supports a per-server cwd field, at the same level as command:

"espctl": {
  "type": "local",
  "command": ["/path/to/espctl", "mcp", "serve"],
  "cwd": "/path/to/your/esp-idf/project",
  "enabled": true,
  "environment": { ... }
}