MCP·Docs

The MCP server.

Connect Zaplens to Claude Code, Cursor, or Claude Desktop in one line. No pipx, no configure step — paste the snippet from your API keys page and your assistant gains eight new tools. Available on Pro and Enterprise.

01Mint a Pro key

Generate one in Settings → API keys. Copy it once.

02Copy the install snippet

The API keys page renders a one-line claude mcp add-json command with your key pre-filled. Same shape works for Cursor and Claude Desktop.

03Start chatting

Eight new tools — launch a sim, stream progress, compare battles, summarise reports — all from inside your AI assistant.

01·Install

Same JSON shape works in Claude Code, Cursor, and Claude Desktop. The /settings/api-keys page inlines your real key into the snippet automatically.

Claude Codeclaude mcp add-json zaplens '…'

The fastest path. Mint a key in Settings → API keys; the dashboard renders this exact command with your key inlined. Copy → paste → done. No pipx, no configure step.

config

claude mcp add-json zaplens '{
  "type": "http",
  "url": "https://api.zaplens.site/mcp/",
  "headers": { "Authorization": "Bearer agl_live_…" }
}'

Codex CLIcodex mcp add zaplens --url … --bearer-token-env-var …

OpenAI's Codex CLI takes the bearer from a shell env var instead of inlining it in config — same HTTP MCP underneath, different secret-handling convention. Add the export to your ~/.zshrc (or shell rc) so it persists across sessions; the dashboard pre-fills the snippet with your actual key.

config

# Add to ~/.zshrc (or your shell rc) so the key persists:
export ZAPLENS_API_KEY="agl_live_…"

# Register with Codex (one-time, picks up the env var at spawn time):
codex mcp add zaplens \
  --url https://api.zaplens.site/mcp/ \
  --bearer-token-env-var ZAPLENS_API_KEY

Cursor~/.cursor/mcp.json

Cursor accepts the same JSON under mcpServers. Picks up changes without a restart.

config

{
  "mcpServers": {
    "zaplens": {
      "type": "http",
      "url": "https://api.zaplens.site/mcp/",
      "headers": { "Authorization": "Bearer agl_live_…" }
    }
  }
}

Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json

Same JSON under mcpServers. Restart Claude Desktop afterwards — it re-reads the config on launch.

config

{
  "mcpServers": {
    "zaplens": {
      "type": "http",
      "url": "https://api.zaplens.site/mcp/",
      "headers": { "Authorization": "Bearer agl_live_…" }
    }
  }
}

02·What your assistant can do

Eight tools. Bias toward synthesis over CRUD — your assistant asks fewer questions and writes shorter chains.

whoami()Sanity-check the connection. Returns the bound account, plan, and credit balance.

query_simulations()List sims newest-first. Filter by status (queued / running / completed / failed) and tag.

launch_simulation()Kick off a new run. Returns immediately with the sim id and an estimated credit ceiling.

wait_for_simulation()Block until a run finishes, streaming progress updates back through MCP's progress channel as it goes. Caps at 30 min by default.

get_simulation_progress()Cheap status snapshot. Safe to poll yourself if you'd rather not block.

summarize_simulation()Bundle sim metadata + report + top 5 pages into one response. The right tool for 'what did the report say?'

cancel_simulation()Stop a running sim. Already-terminal runs return a noop.

compare_battle()Diff two simulations head-to-head — per-entry KPIs with deltas, persona winners/losers, per-URL drop-off, and a verdict line. Pro+ only.

03·Troubleshooting

claude mcp says 'Failed to connect'

Run `claude mcp get zaplens` first and check the stored config: the URL must end with `/mcp/` (trailing slash matters — without it, an HTTPS→HTTP redirect can strip bearer auth on some clients) and the Authorization header must be your full agl_live_… key. Then curl that URL directly with the same headers to see what the server actually returns — a 401 means the key was revoked or wrong, a 404 usually means a missing trailing slash, a timeout means DNS or your network. You don't need to paste your key anywhere new; the bearer is already in ~/.claude.json from the install snippet.

Your client returns 401 on every tool call

The API key in your MCP config was revoked or never existed. Mint a fresh one in Settings → API keys and re-run the install snippet — your client overwrites the previous entry, no manual cleanup needed.

You upgraded plans but tools still say 'API access not included'

The MCP server has no client-side cache, but your editor caches tool definitions per session. Restart the editor and the new plan takes effect immediately.

`claude mcp` says 'unknown transport'

Update Claude Code to v1.0+ — the HTTP transport landed in late 2025. Older versions only know stdio. The stdio install path below still works on any version.

Local stdio install (advanced)

The original install path: a Python CLI installed via pipx that speaks MCP over stdio. Use when you can't reach the hosted endpoint, or when you want the credential read to stay on-device.

install

pipx install zaplens-mcp

configure

zaplens-mcp configure
# Paste your Zaplens API key when prompted.
# Validates against /api/v1/whoami before saving to
# ~/.config/zaplens/credentials.json (mode 0600).

wire into Claude Code

claude mcp add zaplens -- zaplens-mcp serve

Cursor and Claude Desktop use the same JSON shape under mcpServers, with command: "zaplens-mcp" and args: ["serve"].ZAPLENS_API_KEY /ZAPLENS_BASE_URL env vars override the credentials file — handy for CI.

Security note. The HTTP install stores your bearer token in your MCP client's config file (e.g. ~/.claude.json for Claude Code). Same threat model as a .env file — anyone with read access to the file can use the token. Revoke and re-issue if you suspect compromise.