# Etch Agent MCP

> Drive the Etch builder from any MCP-capable agent with typed tools, Project Memory, and a save-gated editing model.

# 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

```text
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](https://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](https://ohmyetch.com/my-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](./first-session.mdx) for the flow in practice.

## Where to go next

- [Install](./install.mdx) - unzip, run one install command, wire up your harness.
- [First Session](./first-session.mdx) - connect a builder tab and make your first (safe) edit.
- [Daily Workflow](./daily-workflow.mdx) - memory, ACSS-aware styling, skills, multiple targets.
- [Tool Reference](./tool-reference.mdx) - all 81 tools grouped by area.
- [Troubleshooting](./troubleshooting.mdx) - empty target lists, port conflicts, safe-mode limits.