Etch Agent MCP
The Etch Agent (etch-agent) is an MCP server that lets AI agents such as Claude Code, Codex, and opencode work inside the Etch builder directly. Instead of screenshots and clipboard round-trips, the agent reads and edits your Etch documents through typed tools, follows the same read-then-edit flow you would, and saves only when you say so.
It ships as a small ZIP you unzip once per machine. No browser extension, no model API keys, no global CLI install.
Mental Model
your agent (Claude Code / Codex / opencode / …)
│ MCP (stdio)
etch-agent server ←→ shared local connector (127.0.0.1:7331)
│ │
│ your authenticated browser
└── typed tools ──► Etch builder tab (AI Connector enabled)
- The server is launched by your harness with Bun and exposes 81 typed Etch tools (as of 2.1.0).
- The connector links the server to an Etch builder tab you already have open. You click AI Connector in the Etch builder; the browser dials out to
127.0.0.1:7331. Your authenticated browser session is the only credential - the agent never sees your WordPress login. - Project Memory is a machine-local store keyed by your site URL, so every session starts by recalling what was previously decided and done on that site.
What you need
| Requirement | Notes |
|---|---|
| Bun 1.3.14 or newer | Runs the MCP server. Install it from bun.sh/docs/installation. |
| An active Etch license | The connector package (@digital-gravy/etch-connector) is installed locally under Digital Gravy's license terms. |
| An authenticated Etch builder tab | Open the Etch builder for the page or template you want to edit, then click AI Connector. |
| The etch-agent ZIP | Download etch-agent-<version>.zip from your OhMyEtch account. |
| Any MCP-capable agent | Claude Code, Codex, and opencode are documented here; any other MCP client works with the same pattern. |
How editing works
The agent never silently publishes changes. Tools split into three effect classes:
| Effect | Tools | When it lands |
|---|---|---|
| Read | trees, blocks, styles, components, fields, memory | Never changes anything. |
| Buffered document edit | block, style, and loop tools | Applied in the open builder document only - visible immediately, saved only when you approve an explicit save. |
| Immediate persist | stylesheets, components, custom fields, Project Memory | Written to the database right away. |
Every step is reversible before saving: etch_undo walks the document back, and switching posts or templates is refused until buffered changes are saved or undone. See First Session for the flow in practice.
Where to go next
- Install - unzip, run one install command, wire up your harness.
- First Session - connect a builder tab and make your first (safe) edit.
- Daily Workflow - memory, ACSS-aware styling, skills, multiple targets.
- Tool Reference - all 81 tools grouped by area.
- Troubleshooting - empty target lists, port conflicts, safe-mode limits.