Scope Analytics

Ask the Scope analyst a natural-language question about this project's analytics. This is the headline tool: it runs Scope's full AI analyst over the project's data — events, LLM inputs/outputs (matched by meaning, not keywords), metrics, and prior investigations — and returns the analyst's reasoned answer, plus the written report when the question calls for one (a recap or digest of a period). Use it for open-ended "why / what / how" questions, e.g. "why did signups drop this week?", "what are users frustrated about?", "how is conversion trending?". (For raw event inspection use scope_query_events; for install coverage use scope_coverage_report.) This runs a real analysis server-side and can take up to a minute or two. It is READ-ONLY — it never changes the project's monitoring config or memory. Relay the answer to the user in your own words. Args: question: The natural-language analytics question to ask the analyst.

Report what Scope analytics is actually capturing for this project, and what's missing. Use this to answer "what does Scope cover for my app?" or after installing Scope to confirm the right layers are flowing. Returns an honest, tenant-scoped data-flow census: which event types and sources are arriving, whether events are quarantined (domain not allow-listed), identity stitching, deploy metadata, and plain-language notes on gaps. Then explain it to the user in your own words. It also lists any DOMAINS AWAITING APPROVAL — events from an unapproved domain are stored but not counted until the user approves it, a common reason a fresh install "looks broken." When that list is non-empty, help the user decide which domains are genuinely theirs and guide them to approve those in Scope. This tool only READS — approving a domain is a click the user makes in Scope's own UI; the MCP never changes settings itself (PRODUCT.md §16). Args: window_hours: Optional look-back window in hours (1–8760). If omitted, the backend uses its configured default window (currently ≈7 days).

Quick check that Scope is receiving events from this project right now. Use right after installing Scope to confirm the pipe is live. Returns whether any events arrived in the recent window and how long ago the most recent event was. Args: window_minutes: Optional recent window in minutes (1–1440). If omitted, the backend uses its configured default window (currently ≈60 min).

Scan this codebase and report what Scope analytics would capture automatically — and what needs a manual step. Read-only and LOCAL (no network): reads dependency manifests (requirements.txt, pyproject.toml, package.json) and config files in the project root and its immediate subdirectories to detect the backend web framework, LLM SDKs, frontend framework, and deploy platform. Use this at install time to answer "what will Scope cover for my app?" from the CODEBASE (before events flow); pair it with scope_coverage_report, which answers the same from the live DATA once events arrive. Then tell the user, in your own words, what's covered and what isn't. Args: path: Project root to scan (defaults to the current directory).

List exactly which LLM SDKs/providers Scope auto-captures (zero-code), by language and canonical package name — the authoritative coverage matrix. Read-only, LOCAL, deterministic (no network, no AI). Use this to answer "does Scope automatically capture my LLM calls?" Enumerate the LLM SDK packages and method calls you see in the user's code, then match them against this list by EXACT package/ method name. Anything NOT listed as auto-captured is NOT auto-captured — Scope still captures everything else (frontend events, backend requests/errors), and an unlisted provider can be captured with a manual scope.track_event(...) call. This is the static source of truth; for a custom wrapper or dynamic provider selection a static check can't be sure about, install and then call scope_coverage_report, which reports from LIVE data which providers are actually arriving. Pair this with scope_detect_stack (which scans the codebase and tells you what was found); this tool tells you, authoritatively, what each of those findings means for coverage.

Takes no parameters.

Check specific LLM SDK identifiers against Scope's auto-capture support — the deterministic per-item checker (read-only, LOCAL, no AI, no network). Enumerate the LLM SDK package names you see in the user's code — the exact dependency strings, e.g. openai, @anthropic-ai/sdk, cohere-ai, ai, google-genai — and pass them here. You get one verdict per identifier: auto-captured (zero-code) / not-auto-captured (with the manual path) / unrecognized. Matching is EXACT (no fuzzy or keyword matching), so pass the canonical package names as written in package.json / requirements; you, the agent, do the code→identifier reading, and this tool gives the authoritative verdict. Pass language ("python" or "node") whenever you know the project's runtime — omitting it returns verdicts for BOTH runtimes (e.g. bare "openai" reports Python and Node), which is noisier than needed for a single-language app. Companion to scope_supported_integrations (the full matrix): use the matrix to see everything; use this to check the specific packages you found. For a custom wrapper or dynamic provider selection a static check can't be sure about, install and then call scope_coverage_report (the live-data ground truth). Args: identifiers: Canonical LLM SDK package names found in the code, e.g. ["openai", "cohere-ai"]. language: Optional "python" or "node" to check only that runtime; omit to check both.

Give the exact steps to install Scope's FRONTEND SDK for this project's stack. Read-only and LOCAL except for one lookup (it fetches this project's public key to embed in the snippet). Scans the codebase to tailor the recommendation (build-time injection for apps with a build step; the one-line script tag for any HTML), and embeds the project's public key (pk_…, safe for client HTML) when available. Use at install time, then APPLY the steps for the user with their confirmation (detect-and-confirm), and run scope_verify_installation to confirm events flow. Args: path: Project root to scan (defaults to the current directory).

Give the exact steps to install Scope's BACKEND SDK for this project's stack. Read-only and LOCAL (no network). Scans the codebase and returns the canonical backend install — for Python, the zero-code `scope-run` path plus the code-based middleware for the detected framework (FastAPI/Flask/Django); for Node, the zero-code `@scope-analytics/node` `--import` bootstrap. Honest about gaps: edge runtimes need the manual wrapper and background workers need scope-run too — it says so rather than emit a command that won't work. The secret key is always a placeholder (never echoed). Apply the steps with the user's confirmation (detect-and-confirm), then run scope_verify_installation. Args: path: Project root to scan (defaults to the current directory).

Query this project's raw analytics events (most recent first). Read-only. Use to inspect what's actually being captured — e.g. the last few LLM calls or page views. For open-ended "why/what" analysis, the Scope analyst (scope_ask) is better; this is the raw feed. Args: event_type: Optional filter by event type. Event-type names are app-specific — call scope_coverage_report first to see which ones this project actually has (e.g. page_view, api_call, llm_call). limit: Max events to return (1–1000; default 20). user_id: Optional filter to a single user's events.

Get this project's headline analytics — total events, unique users, the per-type breakdown, and a day-by-day trend. Read-only, deterministic, and instant (no analysis run). This is the quick "what are the numbers?" tool: use it to size activity or eyeball a trend (growth, a drop-off, a spike) before deciding whether to dig in. Narrow it with a date range and/or a single event type. For the day-by-day counts of one metric over a window this is ideal; for raw rows use scope_query_events, for install/data-flow health use scope_coverage_report, and for an open-ended "why did it change?" hand off to scope_ask. Args: start_date: Optional inclusive start, ISO ("2026-05-01" or a full timestamp). Omit for all time. end_date: Optional inclusive end, ISO. Omit for "up to now". event_type: Optional filter to a single event type (e.g. page_view). Omit for all types.

Reconstruct one session (or one user's activity) across the frontend, backend, and LLM layers, in time order. Read-only. Scope stitches events from all three layers by session, so this returns a single chronological timeline — page views, clicks, backend calls, and LLM calls interleaved — plus a small census (counts by type/source, time span). Use it to see exactly what a user did in a session, or to correlate a session with the code you're looking at. Provide session_id and/or user_id (a user_id also picks up events linked later by identity stitching). Args: session_id: The session to reconstruct (e.g. from scope_query_events output). user_id: A user whose events to gather (matches identity-stitched events too). limit: Max events to return, time-ascending (1–1000; default 200).

List this project's metric definitions — the analyst's recorded recipes for how it computed each metric before (names + one-line definitions). Read-only and instant (no analysis run). Scope's analyst keeps a registry of "how we computed this metric last time" so results stay consistent across questions. Use this to see which metrics exist before asking about them; call scope_get_metric for a metric's full recipe. (These are memory, not rules — the analyst can refine them.)

Takes no parameters.

Get one metric's full recipe — how the Scope analyst computed it last time (the events it selected, joins, window, attribution) plus its provenance and edit history. Read-only and deterministic (the exact recorded recipe, not a paraphrase). Use after scope_list_metrics to inspect exactly how a metric is defined — e.g. to reproduce it in your own code, or to check the analyst's methodology. Pass the exact metric name from scope_list_metrics. Args: name: The exact metric name (as shown by scope_list_metrics).

Connect this MCP to a Scope project WITHOUT anyone copying a key. Start here when the MCP isn't linked yet (the other tools say so). Scope opens in the person's browser; they sign in (or sign up), type the code this returns, choose the project — or create one — and approve. Then call scope_link_wait. The approved link gets its own key, revocable in Scope's Setup → Keys. Args: project_id: The project's id when the person already has one (it's in the prompt Scope's setup page gives them). Leave empty and they pick or create the project on the page. open_browser: Open the page in the person's browser (default true).

Wait for the person to approve the link started by scope_link_project (call it again if it's still waiting). Once approved, every Scope tool works for that project in this session. The key is never shown here: to keep it for the app's server and for next time, ask the person, then call scope_save_key with the app's env file. Args: max_seconds: How long to wait this call (default 90, at most 300).

Save the key the person approved (scope_link_wait) as SCOPE_API_KEY in the app's env file — only if git ignores that file, so it can't be committed. Ask the person before calling it. The key is never shown. The app's server reads it only if its start command loads that file, and in production it must also be set in the host's settings (Vercel, Render, Fly, …). This MCP reads SCOPE_API_KEY from .env.local or .env in the folder it starts in, so a key saved there keeps the project linked next time. Args: env_file: Path to the env file the app's server loads, e.g. /path/to/app/.env

Send the project settings you drafted from the code, as SUGGESTIONS: nothing changes in Scope until the person accepts them on the page scope_link_wait named. Send what you found: {"kind": "product_description", "text": two sentences on what the product does} · {"kind": "domain", "value": an exact host it runs on, "note": "production"} · {"kind": "repo", "url": the GitHub repository} · {"kind": "team_member", "name": …, "email": …, "evidence": "54 commits"} for people in the git history who should get the analyst's reports. A new call replaces what still waits of the same kinds. Metric definitions aren't taken: the analyst defines metrics itself. Args: items: The suggestions, each with a "kind" as above. stack: Optional — what you found, e.g. {"frontend": "Next.js", "backend": "FastAPI", "llm": ["openai"]}. files_changed: Optional — how many files you changed installing Scope.

The project's setup checklist: what is done, what is waiting for data, and what needs the person (suggestions to accept, a site to approve, the GitHub and Slack sign-ins). Use it to end with an accurate summary of what's left for them.

Takes no parameters.

A single-use link for the person to connect Slack to this project (only they can approve it in Slack; you never see Slack's tokens). Give it to them as is.

Takes no parameters.