MCP Tools

Cartographer registers 17 cartographer_* MCP tools on its own FastAPI MCP server (/mcp). IDE agents can create projects, crawl sites, run flows, export Playwright tests, and list traces — without leaving your editor.

This is not the unified cross-product molar_* tool surface (scenario compiler, Guard runs, Clones fleet). Those live on the Platform MCP server in combined-bundle deployments.

Hosted endpoint: https://mcp.molar.cloud · Local: http://localhost:8000/mcp · Dashboard: Integrations → MCP at /dashboard/integrations

Transports and authentication

OAuth (cloud — recommended)

1. Open Integrations → MCP in the dashboard.
2. Choose your IDE and copy the HTTP config snippet.
3. Click Authorize — consent screen scopes access to your org's Cartographer projects.
4. Test with cartographer_list_projects.

Stdio (local / CI)

# Configure CLI
cartog config set api_url https://api.cartographer.molar.it   # or http://localhost:8000
cartog config set token <your-pat>
cartog whoami

# IDE spawns:
cartog mcp

Example Cursor / Claude Desktop config:

{
  "mcpServers": {
    "cartographer": {
      "command": "cartog",
      "args": ["mcp"],
      "env": {
        "CARTOGRAPHER_API_URL": "https://api.cartographer.molar.it",
        "CARTOGRAPHER_API_KEY": "<pat>"
      }
    }
  }
}

MCP tasks and progress events

Long-running tools (cartographer_run_test, cartographer_crawl_site, cartographer_export_test, cartographer_replay_demo with demo_id) report progress via MCP notifications when tasks are enabled:

Task state is persisted to Redis when MCP_EVENTSTORE_REDIS_URL is set (in-process fallback otherwise).

Synchronous mode (tasks disabled): response includes "execution_mode": "synchronous" without mcp_task_id.

Cancel a running agent job: cartographer_cancel.

Tool reference (all 17)

Project management

cartographer_create_project

Create a project for subsequent crawl/run/export calls.

Returns: Created project record (id, name, urls).

cartographer_list_projects

List all projects visible to the authenticated user.

Returns: { "items": [...], "total": N }

Discovery (crawl)

cartographer_crawl_site

Deep-crawl a site and build a route map. Long-running — streams progress.

Returns: route_map_id, status, page_count, pages[], mcp_task_id

cartographer_explore

Alias for cartographer_crawl_site — identical parameters and behavior.

cartographer_list_flows

List discovered flows and route-map pages for a project.

Returns: { "flows": [...], "total": N, "project_id": "..." }

Execution (agent runs)

cartographer_run_test

Run an autonomous flow against a base URL. Long-running — polls until terminal status.

Returns: run_id, status, step_count, stream_url, artifacts[], mcp_task_id

Progress messages: "step N/max — running", terminal status.

cartographer_get_run

Get run status and summary.

Returns: Full run record — status, step count, tier breakdown, artifact URIs, history.

cartographer_list_runs

List agent runs, optionally filtered by project.

Returns: { "runs": [...], "total": N }

cartographer_cancel

Cancel a queued or running agent run.

Returns: Cancellation result with cancelled flag.

Export

cartographer_export_test

Export a completed run to Playwright specs. Long-running — reports pipeline stages.

Returns: export_id, status, files, warnings, testid_coverage_pct, archive_uri, pr_url, mcp_task_id

Progress stages: pruning → ranking → clustering → harvesting → generating → linting → verifying.

cartographer_export_spec

Export with explicit options (queues export, returns immediately with export id).

Returns: Export job record from API.

Artifacts and demos

cartographer_get_artifact

Download run artifact metadata and presigned URLs.

Returns: { "artifacts": { ... } } with signed URLs.

cartographer_replay_demo

Replay a recorded demo as a new agent run, or fetch replay artifacts for an existing run.

Returns (replay): run_id, demo_id, status, stream_url, artifacts, mcp_task_id

Returns (run_id mode): Run status + artifact map without starting new replay.

Traces

cartographer_list_traces

List captured traces for your organization (most recent first).

Returns: { "items": [...], "next_cursor": "..." }

cartographer_get_trace

Get trace metadata and signed artifact URLs.

Returns: Status, retention tier, pinned flag, failure signature, artifact URLs.

Findings

cartographer_get_findings

Passive UX findings (axe, odiff, VLM) for a project.

Returns: { "findings": [...], "total": N }

Task management

cartographer_get_task

Retrieve persisted MCP task state for reconnect/resume.

Returns: Task status, progress, input_json, result_json, or not_found.

Tool summary table

* Long-running when demo_id is provided.

Example workflows

Workflow 1 — Greenfield project from IDE

1. cartographer_create_project
     name: "Acme Staging"
     base_urls: ["https://staging.acme.com"]

2. cartographer_crawl_site
     seed_url: "https://staging.acme.com"
     project_id: <id from step 1>
     max_pages: 100

3. cartographer_list_flows
     project_id: <id>

4. cartographer_run_test
     flow: "Add item to cart and open checkout"
     base_url: "https://staging.acme.com"
     project_id: <id>
     credentials_alias: "staging-user"

5. cartographer_export_test
     run_id: <id from step 4>

Open stream_url in the dashboard to watch live: app.molar.it/dashboard/cartographer.

Workflow 2 — Quick run without project

cartographer_run_test
  flow: "Load homepage and confirm primary nav is visible"
  base_url: "https://example.com"
  max_steps: 15

cartographer_get_run
  run_id: <returned id>

cartographer_export_test
  run_id: <same id>

Workflow 3 — Investigate failure

cartographer_list_runs
  project_id: <id>

cartographer_get_run
  run_id: <failed run>

cartographer_get_artifact
  run_id: <id>
  kind: "screenshots"

cartographer_list_traces
  status: "failed"
  limit: 10

cartographer_get_trace
  trace_id: <id>

cartographer_get_findings
  project_id: <id>
  severity: "critical"

Paste trace share URL from dashboard for teammates.

Workflow 4 — Demo replay after extension recording

cartographer_replay_demo
  demo_id: <from dashboard demos library>
  project_id: <id>
  variables: { "product_sku": "SKU-123" }

cartographer_get_run
  run_id: <replay run_id>

Workflow 5 — Cancel runaway job

cartographer_list_runs
  project_id: <id>

cartographer_cancel
  run_id: <running id>
  mcp_task_id: <optional from run_test response>

Quotas and rate limits

The dashboard Integrations → MCP page shows:

Hosted multi-tenant deployments enforce per-tenant rate limits. Self-hosted operators configure API_RATE_LIMIT_TENANT_* — see Configuration.

CLI (cartog)

The Go CLI talks to the same REST API. Shipped subcommands:

There is no separate cartog subcommand for every MCP tool — use MCP or REST for project creation and trace listing.

Related