DISCOVERY / INSTALLATION / CAPABILITIES

The agent field guide.

PIO Agent is an open-source local Codex plugin, MCP server, and CLI for PlatformIO embedded development. The canonical package and plugin ID are platformio-mcp.

Plain text · llms.txt JSON discovery descriptor Source repository

Where it fits

Use it for PlatformIO board discovery, project setup, firmware builds, structured diagnostics, library investigation, GPIO audits, approved uploads, serial monitoring, and runtime verification. Board and framework compatibility comes from the selected PlatformIO platform.

The full Codex plugin bundles workflow skills and a local dashboard flow. MCP-only setup exposes the server tools without those plugin skills.

Install the Codex plugin

Requires Node.js 20 or newer. Firmware workflows need PlatformIO Core; flashing and physical runtime checks also need compatible connected hardware. Installation changes local configuration and requires user authorization.

npx platformio-mcp install --codex-plugin

Start a new Codex task after installation, then ask: Inspect this PlatformIO project and list the connected boards.

Complete Codex installation, update, and troubleshooting guide

Other host installers

npx platformio-mcp install --codex       # MCP only
npx platformio-mcp install --claude      # Claude Desktop
npx platformio-mcp install --cline
npx platformio-mcp install --vscode
npx platformio-mcp install --antigravity

Restart the host if needed. The runtime executes locally; this website does not offer a remote MCP endpoint.

Generic MCP client configuration

For clients that accept an mcpServers configuration object:

{
  "mcpServers": {
    "platformio": {
      "command": "npx",
      "args": ["-y", "platformio-mcp"]
    }
  }
}

Transport: stdio. On Windows, some hosts need npx.cmd. Hosts with a different configuration format should use their own MCP setup instructions.

Capabilities and boundaries

Task	What the agent gets	What it needs
Inspect	Board/device discovery and project readiness	Local project and host access
Build	PlatformIO compilation and structured diagnostics	PlatformIO Core and target dependencies
Flash	Firmware upload with runtime policy checks	Explicit project/device target and applicable human approval
Verify	Bounded serial evidence and expected boot markers	Connected board, port access, and expected behavior

A successful build does not prove that a physical device works. Existing policy, approval, target-binding, and locking controls remain in force.

Source and distribution

npm contains published package versions. The plugin manifest and repository marketplace describe the source distribution; repository main can be ahead of a release.

This guide and its JSON descriptor document the project. They are not an official directory listing, do not automatically install a plugin, and grant no tool or hardware permissions.