MCP-client integration

Etch is a hosted MCP server at https://etch.systems/mcp. Any MCP-compliant client can attach with a bearer token. The fastest path is an anonymous project token: no signup, 500 signed events, 14-day retention. Every example on this page uses that flow so you can try Etch end-to-end in under two minutes.

Step 1: create an anonymous project token. Run this once in any terminal:

curl -X POST https://etch.systems/v1/your-project

You get back JSON with token (starts with wm_), project_id (starts with anon-), event_cap (500), and mcp_endpoint. Use the token in every client config below.

Config-file locations change from time to time. The links in each section point at the client's own MCP docs so you can double-check the current path if the one below has moved.

Claude Code

Claude Code reads MCP-server config from ~/.claude/settings.json (docs). Add an mcpServers entry:

{
  "mcpServers": {
    "etch": {
      "url": "https://etch.systems/mcp",
      "headers": {
        "Authorization": "Bearer wm_YOUR_ANON_TOKEN"
      }
    }
  }
}

Restart Claude Code after editing. The etch tools appear under /mcp. Every tool call your agent makes lands on the anonymous chain, up to the 500-event cap.

Cursor

Cursor reads MCP config from ~/.cursor/mcp.json for a global setup or .cursor/mcp.json at the project root for a per-project setup (docs). Same JSON shape as Claude Code:

{
  "mcpServers": {
    "etch": {
      "url": "https://etch.systems/mcp",
      "headers": {
        "Authorization": "Bearer wm_YOUR_ANON_TOKEN"
      }
    }
  }
}

Toggle the etch server on in Cursor Settings → Features → MCP to activate.

Continue

Continue reads MCP config from ~/.continue/config.yaml (v1) or ~/.continue/mcpServers/ per-server YAML files (v2) (docs). For v1 config.yaml:

mcpServers:
  - name: etch
    url: https://etch.systems/mcp
    headers:
      Authorization: Bearer wm_YOUR_ANON_TOKEN

Reload the Continue extension after saving.

Cline (VS Code)

Cline stores MCP config in ~/.config/Cline/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json on Linux or the equivalent VS Code storage path on macOS / Windows (docs). Cline uses the same mcpServers shape:

{
  "mcpServers": {
    "etch": {
      "url": "https://etch.systems/mcp",
      "headers": {
        "Authorization": "Bearer wm_YOUR_ANON_TOKEN"
      }
    }
  }
}

The MCP Servers panel in Cline shows a green dot next to etch when the connection is live.

Codex CLI (OpenAI)

Codex CLI reads MCP config from ~/.codex/config.toml (docs). Codex uses TOML, so the shape differs slightly:

[mcp_servers.etch]
url = "https://etch.systems/mcp"
headers = { Authorization = "Bearer wm_YOUR_ANON_TOKEN" }

Verify it worked

Ask your agent to write one signed event, then walk the chain:

curl -H "Authorization: Bearer wm_YOUR_ANON_TOKEN" \
     https://etch.systems/projects/anon-XXXX/audit-log/public-keys

A 200 response means the token authenticates and the chain exists. The public keys returned are what an offline verifier pins to authenticate signed events from your anonymous project.

Cap-hit? Keep the chain.

Once you have written 500 events, POST to /v1/your-project/convert with your anonymous token to move the signed chain to a paid Mode 1 project. The convert response auto-emits a cross_chain_reference event on the new chain so identity continuity is on the record. Full walk-through on the /docs/quickstart page.