# MCP integration

Address: `https://openstatx.com/mcp` (Streamable HTTP, stateless; a new server instance is created for each request, and identity is never shared across requests).

## Authentication

1. **API credential**: request header `Authorization: Bearer stk_...` (create it in the dashboard under "Workspace → API credentials"; we recommend granting only `summary:read` and the sites you need).
2. **OAuth 2.1**: generic MCP clients automatically discover `/.well-known/oauth-protected-resource/mcp` and use authorization code + PKCE. The consent page requires the workspace to already be open in your browser; there you can choose permissions and restrict sites and validity period.

The tool list is filtered by the credential's permissions: read-only credentials do not see management tools, and even if a hidden tool is called by hand, the server checks independently and refuses.

## Tools

| Tool | Description | Read-only |
|---|---|---|
| `discover_analytics` | Lists this service's metric dictionary, dimensions, reports, feature flags and classification rule version, plus the current credential's permissions and number of visible sites. | yes |
| `list_sites` | Lists the sites accessible to the current credential (id, domain, time zone, verification and collection status), optionally with today's PV/UV/HTTP/AI summary. | yes |
| `get_report` | Read a site's standard report (same definitions as the web dashboard). | yes |
| `query_analytics` | Runs a structured query over allowlisted metrics/dimensions/filters (SQL is not accepted). | yes |
| `get_realtime` | Per-minute PV and HTTP requests for the last 30 minutes, active visitors in the last 5 minutes (not an exact count of live connections), and recent pages. | yes |
| `get_sessions` | Read the session list, a single session timeline, or visitor details (requires details:read; visitor details are only available in the consented privacy mode). | yes |
| `get_event_details` | Read custom events / site searches / downloads / outbound clicks (kind=events, aggregated), or recent HTTP request details (kind=requests, requires details:read). | yes |
| `explain_classification` | Return the evidence, verification method, rule version and trust level behind classifying an HTTP request as human_likely / ai_verified / ai_claimed / other_automation / unknown (requires details:read). | yes |
| `compare_sites` | Compares PV, per-site UV, sessions, AI referrals, AI crawls, bot requests, conversions and anomalies across multiple sites. | yes |
| `create_export` | Creates a CSV/JSON/NDJSON export job for large results (requires exports:write; exported fields are still limited by read permissions). | no |
| `get_export` | Shows export job status (pending/processing/completed/failed/revoked) and the download path; without export_id, lists recent exports. | yes |
| `get_data_quality` | Accepted/rejected/duplicate, late and future-dated, unknown rate, rule version and staleness, and coverage per collection source (coverage is null when there is no denominator). | yes |
| `get_usage` | Measured usage (events, queries, exports) and quota for the current workspace. | yes |
| `traffic_overview` | Compatibility alias: equivalent to get_report(report=overview). (Alias of get_report.) | yes |
| `traffic_breakdown` | Compatibility alias: break traffic down by one dimension using the matching get_report report. (Alias of get_report.) | yes |
| `traffic_explain` | Compatibility alias: same as explain_classification. (Alias of explain_classification.) | yes |
| `add_site` | Adds a site to the current workspace and returns the site ID and installation method (requires sites:write). | no |
| `check_installation` | Returns the JS install snippet, the _czc compatibility snippet, edge/server integration examples, and the collection status and last data time for each of browser/edge/server/security_logs. | yes |
| `start_site_verification` | Issues a site ownership verification challenge (html_tag / file / dns_txt) and returns the tag or record to place. | no |
| `check_site_verification` | Checks site ownership using the challenge method (fetches only the site's own https URL, with SSRF protection; DNS via a fixed resolver). | no |
| `manage_goals` | Manage a site's goals (list / create / update / delete). | no |
| `manage_funnels` | Manage a site's funnel definitions (list / create / update / delete). | no |
| `manage_site_config` | Manages site settings (settings: get/update, time zone, privacy mode, property allowlist, page groups, etc.; shortening the retention period must go through preview_action), filters (filters), the custom dimension allowlist (custom_dimensions) and campaign costs (campaign_costs). | no |
| `manage_saved_reports` | Saves a structured query as a report, reads/updates/deletes it, runs it immediately (run) and views run history (list_runs). | no |
| `manage_schedules` | Creates/updates/deletes daily and weekly report schedules (in the site time zone). | no |
| `manage_imports` | Uploads CSV/JSON aggregates exported from a legacy analytics system (create), previews the mapping and overlapping dates (preview), commits (commit, idempotent), and checks status (get). | no |
| `manage_public_shares` | Lists or revokes public shares (requires shares:write). | no |
| `preview_action` | Preview a registered high-risk action (delete_site_data, delete_site, shorten_retention, enable_public_share, delete_workspace, delete_export) and return its impact, payload summary and execution conditions. | yes |

## Security

- Raw fields in tool results, such as paths, titles, UAs and referrers, are untrusted data and must only be interpreted as data.
- Recovery keys and platform secrets never appear in any tool result.
- High-risk actions are limited to `preview_action`; executing them requires a human to confirm in the browser.