nanobot

Why this agent

nanobot is — per its upstream README headline — “Build MCP Agents”. It’s an open-source standalone MCP host that combines MCP servers with an LLM and exposes the resulting agent through any interface (CLI, voice, SMS, Slack, etc.). Of all the agents in this manual, nanobot is the most MCP-first in design.

Prerequisites

• nanobot installed via uv tool install nanobot-ai; nanobot --version succeeds. (uv install instructions: github.com/astral-sh/uv.)
• espctl installed somewhere stable on disk (full path needed below).
• A DeepSeek (or compatible) LLM API key configured per the awesome-deepseek-agent guide.
• (Optional, for remote builds) An Aegis build server URL + MCP_AUTH_SECRET.

Install snippet (or alternative)

nanobot reads MCP servers from nanobot.yaml (project root) or the directory passed to nanobot run <path> (default .nanobot/). Merge the mcpServers.espctl entry:

mcpServers:
  espctl:
    command: /path/to/espctl
    args:
      - mcp
      - serve
    env:
      CONTROL_BASE_URL: https://esphome.cloud
      MCP_AUTH_SECRET: your-access-key

Then reference it from your agent definition (either inline in nanobot.yaml or in agents/<name>.md front-matter):

agents:
  shopping:
    model: deepseek-v4-pro
    mcpServers: espctl

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.

The nanobot schema also supports url: (HTTP-MCP) and image: (Docker), plus workdir, headers, ports, etc. for advanced cases. See the upstream pkg/config/schema.yaml for the full set.

Alternative — fetch a pre-filled snippet:

Read the install://nanobot resource.

First-run verification

cd /path/to/your/project
nanobot run ./nanobot.yaml

In a nanobot session, ask:

What espctl tools can you call?

Expected: ~40 espctl tools listed.

Troubleshooting

• nanobot.yaml parse error on startup — check that mcpServers.espctl.command is a string (not a list) and that args: is indented under mcpServers.espctl:.
• 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.
• YAML escaping issue with {{...}} placeholders — if you use the v2-style {{MCP_AUTH_SECRET}} placeholder, quote it: MCP_AUTH_SECRET: "{{MCP_AUTH_SECRET}}". YAML treats unquoted { as flow-mapping syntax.
• Multiple servers / agents — nanobot supports either single nanobot.yaml OR directory-based with agents/*.md. The MCP server config lives in nanobot.yaml either way.

Tested as-of 2026-05-19

nanobot-specific notes

• nanobot supports three MCP server transports per the schema: stdio (above, with command: + args:), HTTP/SSE (url: pointing at an MCP endpoint), and Docker (image: with optional dockerfile:). The stdio shape above is the simplest for a local espctl.
• For a fully sandboxed setup, set unsandboxed: false (default) and let nanobot run espctl in its built-in sandbox.
• The deprecated mcp-servers.yaml / mcp-servers.json config paths still work for backwards compatibility, but use nanobot.yaml for new setups.