AI agents (MCP)

Echidna includes a Model Context Protocol (MCP) server. Connect an AI app such as Claude Desktop, Claude Code, Codex or Cursor, and the agent can create and organise profiles, open them and browse with human-like input.

How it works

Your AI app starts Echidna's engine program with the arguments mcp --control. It talks to the app over standard input and output, and connects to the engine that the Echidna app is already running. Everything the agent creates or opens shows up in the app.

• Open the Echidna app first and sign in. If no running engine is found, the agent's tools fail with “no running Echidna engine found”.
• Give it your automation token. Turn on Settings → Automation & API and put the token in the server's ECHIDNA_API_TOKEN setting (see the examples below). The agent then has exactly the automation token's powers: profiles, browsers, proxies, flows and schedules, but not your license, saved logins, cards, backups or settings.
• The server finds the engine's address on its own through the api-port file in Echidna's data folder. With a fixed port you can also set ECHIDNA_API_URL, for example http://127.0.0.1:50360.
• The MCP server checks that this computer is signed in before it starts.

The AI agents (MCP) tab in Settings → Automation & API writes these configurations for you, with the engine path of your installation filled in. Turn on Include the token in copied examples to copy them with your token.

Find the engine program

Point your AI app at the engine program inside your Echidna installation:

Replace you with your Windows user name. The AppImage has no fixed install location, so install the .deb if you want to connect an agent on Linux.

Claude Desktop and Cursor

Add Echidna to Claude Desktop's claude_desktop_config.json (Settings → Developer → Edit Config), or to Cursor's mcp.json (~/.cursor/mcp.json; on Windows %USERPROFILE%\.cursor\mcp.json). Both use the same JSON. On macOS:

{
  "mcpServers": {
    "echidna": {
      "command": "/Applications/Echidna.app/Contents/Resources/engine/echidna-engine",
      "args": ["mcp", "--control"],
      "env": { "ECHIDNA_API_TOKEN": "eca_your_automation_token" }
    }
  }
}

On Windows, write the full path with doubled backslashes:

{
  "mcpServers": {
    "echidna": {
      "command": "C:\\Users\\you\\AppData\\Local\\Echidna\\engine\\echidna-engine.exe",
      "args": ["mcp", "--control"],
      "env": { "ECHIDNA_API_TOKEN": "eca_your_automation_token" }
    }
  }
}

Restart the AI app after editing its configuration.

Claude Code

# macOS
claude mcp add echidna --env ECHIDNA_API_TOKEN=eca_your_automation_token -- /Applications/Echidna.app/Contents/Resources/engine/echidna-engine mcp --control

# Linux (.deb)
claude mcp add echidna --env ECHIDNA_API_TOKEN=eca_your_automation_token -- /usr/lib/Echidna/engine/echidna-engine mcp --control

# Windows
claude mcp add echidna --env ECHIDNA_API_TOKEN=eca_your_automation_token -- "C:\Users\you\AppData\Local\Echidna\engine\echidna-engine.exe" mcp --control

Codex

Add a server to ~/.codex/config.toml (on Windows %USERPROFILE%\.codex\config.toml):

[mcp_servers.echidna]
command = "/Applications/Echidna.app/Contents/Resources/engine/echidna-engine"
args = ["mcp", "--control"]
env = { ECHIDNA_API_TOKEN = "eca_your_automation_token" }

What an agent can do

The server offers its tools in groups. With the automation token, the accounts and ops groups and the few tools outside the token's reach (cards and billing, changing settings, captcha keys, autofill and form templates, exports) are left out of the tool list, so the agent is only offered what it can use. Five vault tools stay listed: fill_saved_value, list_cards, get_account, get_totp and wait_for_otp. They work once you turn on Settings → Automation & API → Let scripts use saved cards, billing and logins; until then they answer [forbidden] and name the switch.

Checkout with saved cards

With the switch on, fill_saved_value types one saved card field, billing or shipping field, or the profile's saved login into a field of the open page. The agent never sees the value: the tool answers {ok, card: "••4242"}. list_cards shows id, brand and last 4 digits, so you can tell the agent which card each profile pays with, for example: “For shop-01, shop-02 and shop-03, open the checkout page, fill the billing name and address, then fill the card number, expiry and CVV with the card ending 4242 for shop-01 and 1881 for the others, and stop before paying.” If the automation token leaks, someone could make purchases with your cards, so turn the switch on only while you need it. Every use is listed in Settings → Automation & API and the audit log. See Saved cards, billing and logins.

The guide tool explains Echidna's concepts to the agent, so it can look up how profiles, proxies and flows work before acting.

To give an agent fewer tools, set ECHIDNA_MCP_TOOLSETS in the server's env to a comma-separated list of groups, for example "app,page".

Paced or raw. The agent's own page tools already move and type like a person, so they attach to the browser directly. When an agent hands a profile to your own script with connect_profile, it gets cdp_url, which paces that script's clicks and keys like a hand, and raw_cdp_url, which is faster but sends raw automation input with no mouse path or human timing.

Built-in safety

• A limited token. The automation token can't sign this computer out, read saved passwords or card numbers, restore backups, change settings or update the engine. A refused call answers 403 and changes nothing. Saved cards, billing and logins are closed to it unless you turn on the vault switch, and even then it can only type them, never read them.
• Confirmation for destructive actions. Deleting profiles or proxies, issuing a new fingerprint, clearing cookies or cache, closing all profiles and similar actions first return a preview and change nothing until the agent confirms.
• Secrets stay hidden. Proxy passwords and the engine token never appear in tool output. Cookie values are masked.
• Human-like input. Clicks and typing go through the same human-like input layer as the rest of Echidna and leave no automation markers.
• One driver per profile. A profile being driven by one agent or script is refused to others.
• Limited file access. Files the agent saves stay in ~/.echidna/captures/<profile>/, and uploads are read only from ~/.echidna/uploads/<profile>/.
• Only identity-safe launch options. Window size and position, maximise, mute, notifications, dark mode and images off. Anything touching identity, proxy, debugging or sandboxing is rejected.
• Local only. Everything runs on your computer and talks to the engine over 127.0.0.1.

Changes made through the engine are listed in the app under Activity → Audit log; calls made with the automation token are labelled automation.

If the agent reports that the engine “rejected the automation token”, the token was replaced or automation was turned off: copy the current token from Settings → Automation & API into the configuration and restart the AI app.

Tips

• Keep the Echidna app open while the agent works. Quitting the app closes every browser it started.
• Tell the agent which profiles or group it may use. It sees all of your profiles.
• If you'd rather drive profiles from your own code, use the Engine API.