Reasonix

Why this agent

Reasonix is a DeepSeek-native terminal coding agent — cache-first loop, flash-first cost control, automatic tool-call repair — that talks to api.deepseek.com directly. Per its README it “speaks the Model Context Protocol natively” with three transports (stdio / SSE / Streamable HTTP) and a runtime /mcp add command for ad-hoc additions.

Prerequisites

• Node.js 20.10+ installed.
• Reasonix runs via npx reasonix code (no global install required).
• A DeepSeek API key (Reasonix’s first-run wizard prompts for it and saves to ~/.reasonix/config.json).
• 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)

Reasonix’s canonical MCP-server format goes under the mcpServers field of ~/.reasonix/config.json (or <project>/.reasonix/config.json for per-project). Merge the following entry — the shape is identical to Claude Code’s mcpServers:

{
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "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.
• CONTROL_BASE_URL — your Aegis build server URL.
• MCP_AUTH_SECRET — your access key from the build server.

Alternative — fetch a pre-filled snippet:

Read the install://reasonix resource.

Or use Reasonix’s runtime /mcp add slash command to add espctl without editing the config file:

/mcp add espctl=/path/to/espctl mcp serve

(Reasonix’s CLI-flag-compatible legacy form. See esengine.github.io/DeepSeek-Reasonix/configuration.html#mcp for the full schema.)

First-run verification

cd /path/to/your/esp-idf/project
npx reasonix code

In the Reasonix session, ask:

What espctl tools do you have?

Expected: ~40 espctl tools listed. You can also run reasonix doctor for a Node + API-key + MCP-wiring health check.

Troubleshooting

• config.json parse error on startup — ~/.reasonix/config.json combines many sections (auth, mcpServers, skills, hooks, etc.). If Reasonix can’t parse it, run reasonix doctor for the offending line. Common cause: dangling comma after the last mcpServers entry.
• 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 instead of stdio? Reasonix supports the transport: "sse" (or "streamable+https://...") shape — replace the espctl entry with:

  "espctl": {
    "transport": "sse",
    "url": "https://esphome.cloud/mcp/esp-idf",
    "headers": {
      "Authorization": "Bearer your-access-key"
    }
  }
  

• Claude-format skills also load — per the README, Reasonix reads <project>/.claude/skills/ and ~/.claude/skills/ alongside its native skill paths. So Claude-Code-shipping skills work in Reasonix too.

Tested as-of 2026-05-19

Reasonix-specific notes

• Two config formats for MCP are accepted: legacy string array ("mcp": ["name=cmd args"], CLI-flag-compatible) and canonical object ("mcpServers": {...}, used above). The canonical form is preferred for namespaced env vars and per-server disabled flags.
• reasonix mcp subcommand for listing/managing registered MCP servers; see reasonix --help for the full reference.
• The Reasonix docs at esengine.github.io/DeepSeek-Reasonix cover all config.json sections (auth, MCP, skills, memory, hooks, permissions, web search, semantic index).