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)

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)

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.)