scope-analytics-mcp

Scope MCP server

The unified Scope MCP server (PRODUCT.md §16) — one server an AI coding agent (Claude Code, Cursor, ChatGPT, …) uses both to install Scope analytics in a project and to query it afterward. Scope is the AI analyst for AI products; this is its programmatic surface.

Tools

Install / setup (run once, at install time)

Tool	What it does
scope_detect_stack	Scans the codebase (local, no key) and reports what Scope would auto-instrument for your stack — backend framework, LLM SDKs, frontend, deploy platform — plus honest non-coverage.
scope_install_frontend	The exact frontend-SDK install steps tailored to your stack (build-time injection or the one-line script tag), with your project's public key embedded.
scope_install_backend	The exact backend-SDK install steps for your stack — the zero-code scope-run path plus the code-based middleware (FastAPI/Flask/Django). Honest when a path isn't shipped yet (e.g. a Node backend).
scope_coverage_report	Honest, tenant-scoped data-flow census: which event types/sources are flowing, quarantine state, identity stitching, deploy metadata, and notes on gaps.
scope_verify_installation	Quick "are events flowing right now?" check, for right after install.

The install tools propose code changes; your agent shows them to you and applies them on your confirmation (detect-and-confirm). The Scope MCP never silently writes your files, and your secret key is never echoed into a snippet — only a placeholder.

Query (ongoing analysis)

Tool	What it does
scope_ask	Natural-language analytics question → the analyst's full reasoned answer (findings + recommendations). The catch-all; runs a real server-side agent loop (can take a minute).
scope_get_stats	Headline counts — total events, unique users, the per-type breakdown, and a day-by-day trend — over an optional date range / event type. Instant and deterministic; the quick "what are the numbers?" before deciding whether to dig in.
scope_query_events	The raw event feed (most recent first), optionally filtered by type/user.
scope_get_session	One session's (or user's) events stitched across frontend + backend + LLM, in time order, with a small census.
scope_list_metrics	The project's metric definitions — the analyst's recorded recipes ("how we computed it last time").
scope_get_metric	One metric's full recipe + provenance.

All query tools are read-only and tenant-scoped to your key's project. Use the deterministic primitives for instant lookups you compose yourself; use scope_ask for open-ended "why/what/how".

Configure (auth = your project SECRET key in the MCP config)

env keys:

• SCOPE_API_KEY — required. Your project's secret key (sk_...), from the Scope dashboard. (The install tools also read your public key from the API; you don't configure it.)
• SCOPE_API_BASE — backend base URL. Optional; defaults to https://api.scopeai.dev (the Scope production backend). Override only for self-hosted / staging deployments.
• SCOPE_API_TIMEOUT — request timeout seconds (default 90; the free-tier backend can cold-start, and scope_ask runs a real agent loop, so its client floors the timeout at 180s).

Published as scope-analytics-mcp on PyPI — uvx fetches + runs it on demand (no manual install). It's a standard stdio server, so it drops into any MCP-capable coding agent; SCOPE_API_BASE is optional (defaults to https://api.scopeai.dev).

Claude Code (.mcp.json or claude mcp add)

{
  "mcpServers": {
    "scope": {
      "command": "uvx",
      "args": ["scope-analytics-mcp"],
      "env": {
        "SCOPE_API_KEY": "sk_...",
        "SCOPE_API_BASE": "https://api.scopeai.dev"
      }
    }
  }
}

Or from the CLI: claude mcp add scope --env SCOPE_API_KEY=sk_... -- uvx scope-analytics-mcp

Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

Identical stdio schema — drop the same mcpServers block into ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). A one-click Add to Cursor deeplink is also available:

cursor://anysphere.cursor-deeplink/mcp/install?name=scope-analytics&config=<base64 of the inner server object — {command, args, env}, not the mcpServers wrapper>

Codex CLI (~/.codex/config.toml)

[mcp_servers.scope]
command = "uvx"
args = ["scope-analytics-mcp"]
startup_timeout_sec = 30   # cushion for the first-run uvx fetch

[mcp_servers.scope.env]
SCOPE_API_KEY = "sk_..."

Or from the CLI: codex mcp add scope --env SCOPE_API_KEY=sk_... -- uvx scope-analytics-mcp

Running from a local checkout (development): swap the command for your venv python and the import name — "command": "/path/to/mcp-server/venv/bin/python", "args": ["-m", "scope_mcp"] (the import package stays scope_mcp; the PyPI/uvx name is scope-analytics-mcp).

Then ask your agent things like:

• "Use Scope to install analytics in this project." (→ detect → install → verify)
• "What does Scope cover for my app?" (→ coverage report)
• "Ask Scope why signups dropped this week." (→ the analyst)
• "Show me what user u_123 did in their last session." (→ session)

Develop

python3.10 -m venv venv
venv/bin/pip install -e ".[dev]"
venv/bin/python -m pytest -q

Not yet shipped (Track C): the sharing tools (scope_list_reports, scope_get_report, …) and the cross-origin CORS opt-in action. (A multi-project project_id arg is intentionally not planned — configure one MCP server per project so each is cleanly tenant-isolated by its own key.)