Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Pi

Why this agent

Pi (by Mario Zechner; pi.dev) is a minimal, aggressively-extensible terminal coding harness with tree-structured sessions and custom-provider support. It’s the parent project Oh My Pi was forked from.

Pi’s relationship to MCP is opinionated: Mario explicitly chose not to bake MCP into Pi’s core. The upstream packages/coding-agent/README.md states verbatim:

No MCP. Build CLI tools with READMEs (see Skills), or build an extension that adds MCP support. Why?

Espctl can still drive Pi — just not via the install:// MCP path that works for the other coding-agent clients in this manual.

Prerequisites

  • Pi installed (npx -y @earendil-works/pi-coding-agent@latest or per the upstream install docs at https://pi.dev).
  • One of the alternative paths below (espctl skill, MCP extension, or the human-in-the-loop delegation pattern).

Install snippet (or alternative)

Pi is a documented-stub in this MCP coverage by upstream design — not pending verification. There is no Pi-side MCP-server config slot, because Pi’s design philosophy explicitly rejects MCP as a core abstraction (Mario’s post linked above explains the “what if you don’t need MCP” argument).

The Pi-aligned paths to espctl are:

  1. Skill-based — write an espctl skill (a folder with a SKILL.md + helper scripts) under ~/.pi/agent/skills/espctl/ that shells out to espctl build, espctl flash, etc. directly. This is the Pi-native pattern; see the Pi Skills docs.

  2. MCP-bridge extension — write a TypeScript extension under ~/.pi/agent/extensions/mcp-bridge/ that registers an MCP client against this MCP coverage. The upstream README explicitly lists “MCP server integration” as a valid extension use case (line 368). No such extension ships with Pi today; you’d be writing the first.

  3. Browser-side HTTP MCP endpoint — drive https://esphome.cloud/mcp/esp-idf directly from Pi via Pi’s built-in bash tool + curl. Crude but works without any extension or skill.

  4. Human-in-the-loop delegation — use Pi for editing / refactoring; delegate concrete firmware operations to a Claude Code, Cursor, Codex CLI, or Crush session with this MCP coverage wired in via install://claude-code (or equivalent).

For most users, path 4 is the easiest. Path 1 is the “correct” Pi-native solution if you want a long-term espctl integration without depending on MCP at all.

First-run verification

For paths 1–3, verify the alternative endpoint is reachable:

curl -fsSL https://esphome.cloud/mcp/esp-idf | head -1

Expected: 200 OK JSON response.

For path 4, verification is whichever coding-agent session you delegate to (see Claude Code etc.).

Troubleshooting

  • mcp/esp-idf returns 404 / 5xx — check esphome.cloud status.
  • Want a verified install snippet? Pi’s “no MCP” stance is a deliberate upstream design choice. The way to get espctl in Pi is to write a skill or extension — neither is something this MCP coverage ships today. If the Pi-mono project ever changes its position on MCP, this page flips. Track badlogic/pi-mono.
  • Relationship to Oh My Pi — Oh My Pi (a Pi fork) added .claude/... config inheritance for MCP support. If you want out-of-the-box espctl support in a Pi-derivative shell, use Oh My Pi instead.

Tested as-of 2026-05-19

Pi-specific notes

  • Pi’s docs distinguish three extension surfaces: Skills (CLI-tool-style; just write a folder with SKILL.md), Extensions (TypeScript code with full Pi API access), and Pi Packages (npm / git distribution wrapper).
  • A “first MCP extension for Pi” would be a useful community contribution if the Pi ecosystem grows interest in MCP. It’s not on the this MCP coverage roadmap.