# extension.report MCP server

> Read-only, OAuth-scoped analytics and diagnostics for browser extensions and apps. Use it to debug production errors, investigate one installation, assess a release, build dashboards, or write operating reports.

Documentation version: 2026-07-16
MCP endpoint: https://extension.report/mcp
Transport: Streamable HTTP
Authentication: OAuth 2.1 authorization code with PKCE
Protected resource metadata: https://extension.report/.well-known/oauth-protected-resource/mcp
Authorization server metadata: https://extension.report/.well-known/oauth-authorization-server/api/auth
Human documentation: https://extension.report/docs/mcp

## Agent connection

Give an MCP-compatible client the URL https://extension.report/mcp. The server advertises OAuth metadata through the WWW-Authenticate challenge and supports dynamic public-client registration. The user signs in to extension.report and explicitly approves read-only scopes. Do not ask for a project secret or place one in agent configuration.

Scopes:
- analytics:read: projects, installed population, metrics, feature usage, breakdowns, and retention.
- diagnostics:read: redacted events, error groups, installation traces, and release health.
- offline_access: optional refresh access requested by the client.

## Tool catalog

- get_context [analytics:read]: Discover accessible projects, retention, scopes, and time semantics. Always start here.
- get_project_overview [analytics:read]: Get installed population, acquisition/churn flows, adoption, yesterday's report, and active alerts.
- query_metrics [analytics:read]: Get exact daily metric series and totals with optional version, country, or browser filters.
- query_product_usage [analytics:read]: Discover and query custom feature events for product adoption and dashboards.
- query_breakdown [analytics:read]: Break installs, uninstalls, active installations, or events down by version, country, or browser.
- query_retention [analytics:read]: Get denominator-backed retention plus weekly retained, resurrected, and churned populations.
- search_events [diagnostics:read]: Search redacted event evidence with filters and opaque pagination.
- query_errors [diagnostics:read]: Group SDK error reports by stable fingerprint and inspect affected versions and populations.
- get_installation_timeline [diagnostics:read]: Inspect a chronological trace for one exact installation id.
- get_release_health [diagnostics:read]: Compare version rollout, errors, uninstalls, active population, and update lag.

All tools are declared read-only, non-destructive, idempotent, and closed-world. Every response uses a stable envelope:

    { "ok": true, "data": {}, "meta": { "requestId": "...", "generatedAt": "...", "projectId": "...", "range": { "start": "...", "end": "...", "timezone": "UTC" }, "retentionDays": 30 } }

Errors use:

    { "ok": false, "error": { "code": "...", "message": "...", "retryable": false }, "meta": { "requestId": "..." } }

## Required reasoning contracts

- Start with get_context, then get_project_overview.
- Usage metrics are attributed to the event's occurred_at UTC day. received_at is reserved for ingestion health and rollout observation.
- Installed means known and not observed as uninstalled. Active means seen in the displayed window. Engaged means opened or used in that window.
- Never mix two time windows in one visualization.
- Every rate needs a numerator, denominator, and reference. Below 50 known installed extensions, prefer counts to percentages.
- The server enforces the user's plan retention. A requested start earlier than retention may be clamped; read meta.range and meta.retentionDays.
- Raw event results are capped and use an opaque cursor. Follow nextCursor only when needed.
- Event attributes are redacted before leaving the server. Do not treat missing redacted fields as missing production data.
- Error reports are deduplicated at SDK collection time by fingerprint. reports is not an uncaught-exception occurrence counter.
- Separate observations from hypotheses. Do not claim a root cause solely from correlation by version.

## Debug a production extension error

1. get_context -> choose the project id.
2. get_project_overview -> identify active alerts and the affected operating window.
3. query_errors -> find stable fingerprints, affected installations, versions, first seen, and last seen.
4. get_release_health -> compare the suspected release with neighboring versions.
5. get_installation_timeline -> inspect only a small affected sample around the error.
6. If the stack is minified, keep source maps local:

       pnpm dlx @extension-report/doctor --symbolicate stack.txt --source-map dist/background.js.map

   extension.report never needs the source map and the doctor does not upload it.

## Build a dashboard or report

1. Establish one UTC range with get_project_overview.
2. query_metrics for acquisition, churn, installed activity, and engagement flows.
3. query_product_usage for the user workflow named in the reporting objective.
4. query_breakdown only for a decision-relevant version, country, or browser dimension.
5. query_retention for denominator-backed longitudinal behavior.
6. State the range, population, retention limit, and confidence in the output.

## MCP resources and prompts

Resources:
- extension-report://guide
- extension-report://projects/{projectId}/capabilities

Prompts:
- debug-extension-error
- build-analytics-dashboard
- write-executive-report

## Security and privacy

- No write tools exist in V1.
- OAuth permissions are tied to the signed-in user; project authorization is checked on every tool call.
- Workspace and project MCP kill switches apply immediately.
- Analytics and diagnostics use separate rate-limit buckets.
- Audit logs store tool, user, OAuth client, project, timing, status, and row count. They do not store tool arguments or results.
- MCP audit metadata is automatically purged after 90 days by the analytics retention maintenance job.
- Sensitive attribute keys, response bodies, authorization values, cookies, tokens, and secrets are redacted defensively.