MCP·Docs

The MCP server.

Connect AgentLens to Claude Desktop, Cursor, or Claude Code. Two commands to install, one to configure. Available on Pro and Enterprise.

01Mint a Pro key

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

02Install + configure

One pipx command, one paste-in of your key. Validates against /api/v1/whoami so a bad key fails loudly.

03Drop into your editor

Add one JSON block to Claude Desktop / Cursor. Your assistant gets eight new AgentLens tools.

01·Install

The MCP server ships as a single Python package. We recommend pipx so it lives in its own venv and doesn't collide with your system Python.

install

pipx install agentlens-mcp

No pipx? pip install agentlens-mcp works too — just be aware it installs into whatever Python is currently active.

02·Configure

Run configure once. It prompts for your API key, hits /api/v1/whoami to make sure it works, then writes ~/.config/agentlens/credentials.json with mode 0600.

configure

agentlens-mcp configure
# Paste your AgentLens API key.
# Create one at https://agentlens.example/settings/api-keys (Pro or Enterprise plan).
#
# Key: agl_live_xxxxxxxxxxxxxxxxxxxxxxxx
#
# ✓ Authenticated as 'ACME UX team' on the 'pro' plan (8,432 credits remaining).
# ✓ Saved to /Users/you/.config/agentlens/credentials.json

Prefer environment variables? AGENTLENS_API_KEY (and optionally AGENTLENS_BASE_URL) override the file. Useful in CI.

03·Wire it into your editor

Same JSON block works in Claude Desktop, Cursor, and Claude Code.

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

Add the AgentLens server to the mcpServers map. Restart Claude Desktop afterwards — it only re-reads the config on launch.

config

{
  "mcpServers": {
    "agentlens": {
      "command": "agentlens-mcp",
      "args": ["serve"]
    }
  }
}

Cursor~/.cursor/mcp.json

Identical shape. Cursor picks up changes without a restart.

config

{
  "mcpServers": {
    "agentlens": {
      "command": "agentlens-mcp",
      "args": ["serve"]
    }
  }
}

Claude Codeclaude mcp add agentlens -- agentlens-mcp serve

Use the CLI helper rather than editing config by hand. It writes the same JSON shape under the hood.

config

claude mcp add agentlens -- agentlens-mcp serve

04·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.

05·Troubleshooting

Your assistant says it can't reach AgentLens

Run agentlens-mcp doctor — it re-validates your stored key against the same endpoint the server uses on every tool call. Most failures are a revoked key (mint a fresh one) or a plan downgrade (you need Pro+).

terminal

agentlens-mcp doctor
# ✓ 'ACME UX team' on plan 'pro', 8,432 credits remaining.

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

The MCP server caches nothing — but your Claude Desktop / Cursor session does cache tool definitions. Restart the editor and the new plan takes effect immediately.

The server starts but no tools show up in your client

Confirm the editor is invoking 'agentlens-mcp serve' (not just 'agentlens-mcp'). The 'serve' subcommand is what speaks MCP over stdio — the bare command prints help and exits.

Security note. The MCP server stores your API key in ~/.config/agentlens/credentials.json (mode 0600). Anyone with read access to your home directory can use it — revoke and re-issue if you suspect compromise. OS keychain integration is coming in v2.