Install

The fastest path: unzip the package and tell your agent to read the bundled onboarding.md. It detects the harness, merges the config, and verifies the connection for you. This page is the same procedure written out for humans, with Claude Code, Codex, and opencode as the worked examples - any other MCP client follows the same shape.

Unzip and install the runtime

Extract etch-agent-<version>.zip into a durable location, for example:

etch-agent/
├── README.md
├── AGENTS.md
├── CHANGELOG.md
├── onboarding.md
├── LICENSE
└── mcp/
    ├── server.js            ← the MCP server your harness launches
    ├── package.json         ← locked runtime manifest
    ├── bun.lock
    └── skills/              ← core and user agent skills

The unzipped folder name is version-agnostic, so a future release can be dropped over the same path without touching your MCP config. The version lives in the ZIP filename and CHANGELOG.md.

Then install the locked runtime from the package root:

bun install --cwd mcp --frozen-lockfile --no-save

This installs the connector (@digital-gravy/etch-connector), ws, and zod locally inside mcp/node_modules/. The ZIP deliberately contains no connector code - it is installed on your machine, under its own license terms, at review-pinned versions.

Check your Bun version first (bun --version); 1.3.14 or newer is required.

Values every config needs

Two absolute paths go into every harness config:

Placeholder	Meaning	How to get it
`SERVER_PATH`	Absolute path to `mcp/server.js` inside the unzipped package.	Run `pwd` inside `mcp/` and append `/server.js`.
`BUN_PATH`	Absolute path to the `bun` binary.	Run `which bun`. If the harness inherits your shell PATH, the plain string `"bun"` works.

Also pick a --client-name value (e.g. claude, codex, opencode) - it only labels the instance in startup logs.

Claude Code

Project-scoped config in .mcp.json at the project root, or a global entry under the top-level mcpServers object of ~/.claude.json:

{
  "mcpServers": {
    "etch-agent": {
      "command": "BUN_PATH",
      "args": ["SERVER_PATH", "--client-name", "claude"]
    }
  }
}

Merge into the existing mcpServers object; do not overwrite other entries. Restart Claude Code afterwards.

Codex

Config file: ~/.codex/config.toml. TOML, not JSON:

[mcp_servers.etch-agent]
command = "BUN_PATH"
args = ["SERVER_PATH", "--client-name", "codex"]

Append to the existing file; do not overwrite other [mcp_servers.*] blocks. Restart Codex afterwards.

opencode

Config file: ~/.config/opencode/opencode.json. Note the shape differs from Claude Code: a single command array under mcp, no separate args:

{
  "mcp": {
    "etch-agent": {
      "type": "local",
      "command": ["BUN_PATH", "SERVER_PATH", "--client-name", "opencode"]
    }
  }
}

Restart opencode afterwards.

Other harnesses

Most MCP clients use the Claude Code JSON shape - put etch-agent under the client's own mcpServers key:

Harness	Config location
Claude Desktop	`claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`)
Cursor	`.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
ZCode	Settings UI → MCP Servers → paste the entry into Full configuration (scope: User)

The ZCode entry uses this JSON in the UI:

{
  "etch-agent": {
    "type": "stdio",
    "command": "BUN_PATH",
    "args": ["SERVER_PATH", "--client-name", "zcode"],
    "env": {}
  }
}

Run several harnesses at once

The connector is shared, not exclusive. The first harness to start becomes the connector host (it owns ports 7331 and 7332); any harness started afterwards detects it and reuses it. You can install etch-agent into Claude Code, Codex, and opencode at the same time and run them simultaneously.

Two rules:

Only one agent should mutate the same Etch target at a time. Two agents editing the same builder tab will collide. Different targets in different tabs are fine.
For an isolated instance (a scratch harness that must not share the connector), add a distinct port argument such as --connector-ws-port 17331. A custom port runs standalone: it hosts nothing and reuses nothing.

Verify the installation

Connector is up. The first harness's startup log should read [etch-agent:<name>] hosting the connector (host mode); any harness started later should read reusing an existing connector (client mode).
A target answers. Log into WordPress, open the Etch builder for a page or template, and click AI Connector in the builder. Then ask your agent to call etch_list_targets - your tab should appear with its URL and title.

If etch_list_targets comes back empty, see Troubleshooting.

Unzip and install the runtime​

Values every config needs​

Claude Code​

Codex​

opencode​

Other harnesses​

Run several harnesses at once​

Verify the installation​