MCP · read-only V1

Give AI agents production context for your extension.

Connect Codex, Claude, or any compatible agent to extension.report through MCP. The agent can investigate redacted errors and event traces, assess releases, query product analytics, or build reports without receiving a project secret or write access.

Machine-readable version: /docs/mcp.txt

Connect an agent

Give the client one URL. OAuth discovery, public-client discovery through CIMD (with dynamic registration fallback), sign-in, project consent, and token refresh follow standard metadata.

MCP server URL: https://extension.report/mcp
Transport: Streamable HTTP
Authentication: OAuth 2.1 + PKCE
Credentials: none to copy or paste

Read analytics

analytics:read

Projects, populations, daily metrics, product usage, breakdowns, and retention.

Read diagnostics

diagnostics:read

Redacted events and errors, installation traces, and release health.

OAuth access is bound to the signed-in user. Every tool call checks that user's current project access and the workspace/project MCP switches. The Free plan includes MCP and keeps its normal retention limit. Consent covers selected projects, or future projects only when explicitly enabled. Within an authorized project, every analytics property is available—there is no property-level allowlist.

Client setup

Do not create an API key or manually configure OAuth endpoints.

Codex

Add a remote MCP server in MCP settings and enter only the server URL above.

Claude

Add a custom remote connector and use the server URL above; the browser completes OAuth.

Other MCP clients

Choose Streamable HTTP, enter the URL, and let protected-resource discovery start OAuth.

Tool surface

Seventeen focused tools make selection predictable for agents. All are declared read-only, non-destructive, and idempotent.

Tool	Scope	When an agent should use it
get_context	analytics:read or diagnostics: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 complete daily custom-feature series over at most 90 days.
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.
get_metric_catalog	analytics:read	Read metric semantics, units, aggregations, time attribution, and population definitions.
get_event_catalog	analytics:read	Discover event types actually observed in the requested range with counts and coverage.
query_funnel	analytics:read	Get a progressively intersected usage funnel with visible denominators.
query_usage_counters	analytics:read	Query complete custom-event and SDK daily-counter series over at most 31 days.
compare_periods	analytics:read	Compare a range with the immediately preceding equal period using correct aggregations.
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_error_occurrences	diagnostics:read	Turn an error fingerprint into redacted event and installation samples for investigation.
get_installation_timeline	diagnostics:read	Inspect a reverse-chronological, page-stable trace for one exact installation id.
get_release_health	diagnostics:read	Compare version rollout, errors, uninstalls, active population, and update lag.
get_data_quality	diagnostics:read	Inspect coverage, freshness, observed days, and delayed telemetry before drawing conclusions.

Debug an extension error

An evidence-first path from symptom to a supported correction.

1
Discover
Call get_context and select a project id.
2
Triage
Call get_project_overview, then query_errors for the suspected UTC window.
3
Sample
Call get_error_occurrences for the fingerprint and select one affected installation.
4
Compare
Use get_release_health to test whether the signal follows a version rollout.
5
Trace
Inspect the minimum useful sample with get_installation_timeline.
6
Symbolicate
Run the doctor locally with your private source map; no source upload is required.

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

Source maps and source content remain on the developer's machine. The helper maps returned minified frames locally and performs no network request in symbolication mode.

Data contracts agents must preserve

Usage uses occurred_at in UTC; ingestion monitoring uses received_at.
Installed, active, and engaged are distinct populations. One visualization uses one window.
Every rate needs a numerator, denominator, and reference. Below 50 installed extensions, prefer counts.
Plan retention is enforced server-side and reported in response metadata. Both requested and effective ranges are returned; absence outside the effective range is unknown, not zero.
SDK error reports are fingerprint-deduplicated; report count is not an exception-occurrence counter.

Security boundaries

No V1 tool can mutate product or account state.
Diagnostics canonicalize sensitive keys and redact credentials, tokens, emails, URL credentials, cookies, and oversized nested content. Redaction counts accompany telemetry.
Event names, properties, URLs, errors, and stacks are untrusted evidence and can never act as instructions to an agent.
Analytics and diagnostics have separate permissions and rate limits.
Audit rows record identity, client, project, tool, status, duration, and row count—not arguments or results.
Connections can be revoked and MCP can be disabled globally, by workspace, member, or project.

Build dashboards and operating reports

The same surface supports recurring reporting without exposing raw credentials.

Start with get_project_overview, establish one UTC period, then select only the required series, usage events, breakdowns, funnel, and retention evidence. Use compare_periods for change and get_data_quality before asserting missing data. State the requested/effective period, population, retention limit, and confidence alongside the result.

The server also exposes the prompts build-analytics-dashboard and write-executive-report, plus a resource describing each project's current capabilities.