Scope MCP server

The unified Scope MCP server (PRODUCT.md §16) — one server an AI coding agent (Claude Code, Cursor, ChatGPT, …) uses to set up a Scope project, install Scope analytics in it, and query it afterward. Scope is the AI analyst for AI products; this is its programmatic surface. It needs no key to start: the agent links it to a project, and the person approves that in their browser.

Tools

Set up a project (no key needed)

Install (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 (no key needed)

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. Add it with no key at all; the first time your agent uses it, it links the project with scope_link_project and you approve that in your browser.

Claude Code

claude mcp add scope -- uvx scope-analytics-mcp

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

{
  "mcpServers": {
    "scope": {
      "command": "uvx",
      "args": ["scope-analytics-mcp"]
    }
  }
}

Or one click with Add to Cursor on your project's Setup → Get started page in Scope — or paste this into your browser's address bar:

cursor://anysphere.cursor-deeplink/mcp/install?name=scope&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJzY29wZS1hbmFseXRpY3MtbWNwIl19

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

Optional settings (env)

• SCOPE_API_KEY — a project's secret key (sk_...). Optional. Without it the MCP uses the key a link saved in .env.local or .env in the folder it runs in, and otherwise asks your agent to link the project. Set it only to pin one project, and keep it out of project files (.mcp.json, .cursor/mcp.json) that get committed: claude mcp add scope --env SCOPE_API_KEY="$SCOPE_API_KEY" -- uvx scope-analytics-mcp stores it in ~/.claude.json in your home folder, never your repo; in Cursor, reference it from your environment with "env": { "SCOPE_API_KEY": "${env:SCOPE_API_KEY}" }. The install tools read your public key from the API; you don't configure it.
• SCOPE_API_BASE — backend base URL. 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).

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:

• "Set up Scope for this project." (→ link → install → suggestions → status)
• "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 — the MCP works on one project at a time, the one its key belongs to: the key linked in the folder it runs in, or SCOPE_API_KEY. Each project stays cleanly tenant-isolated by its own key.)