Delivery
MCP server
Let an AI agent query your analytics — read-only, with evidence.
What it is#
A Model Context Protocol server, so Claude, Cursor, Codex or your own agent can read your analytics directly. One endpoint:
https://app.vitrus.dev/mcp
Two ways in. Clients that support it sign in with OAuth: you add the URL, a browser window opens, you pick a workspace and click Allow. Everything else takes a workspace API key (Workspace → API keys, admins only, shown once). Either way the connection reads one workspace, can never write, and you can cut it off: OAuth apps under Account → Connected apps, keys under API keys.
Connecting#
ChatGPT (Plus, Pro, Business, Enterprise, Edu — web): Settings → Apps & Connectors → enable developer mode,
then add a connector with the URL https://app.vitrus.dev/mcp and sign in.
Claude (claude.ai and the desktop app): Settings → Connectors → Add custom connector →
https://app.vitrus.dev/mcp, then Connect and sign in.
Claude Code, with OAuth (then run /mcp and choose Authenticate):
claude mcp add vitrus --scope user --transport http https://app.vitrus.dev/mcp
…or with an API key, no browser step:
claude mcp add vitrus --scope user --transport http https://app.vitrus.dev/mcp --header "Authorization: Bearer vk_YOUR_KEY"
Claude Code plugin — the server plus four skills (/vitrus:weekly-report,
/vitrus:traffic-drop, /vitrus:measurement-plan,
/vitrus:ai-search-audit):
claude plugin marketplace add Vitrus-Dev/vitrus claude plugin install vitrus@vitrus
Cursor — one click: Add Vitrus to Cursor.
Gemini CLI: gemini extensions install https://github.com/Vitrus-Dev/vitrus.
The server is listed in the official MCP Registry as dev.vitrus/analytics.
Cursor by hand (~/.cursor/mcp.json), Windsurf, Claude Desktop and any client that takes a JSON config —
leave out headers to sign in with OAuth instead:
{
"mcpServers": {
"vitrus": {
"type": "http",
"url": "https://app.vitrus.dev/mcp",
"headers": { "Authorization": "Bearer vk_YOUR_KEY" }
}
}
}
Transport is plain HTTP, one JSON-RPC POST per call, protocol 2025-06-18.
OAuth follows the MCP authorization spec: discovery via
/.well-known/oauth-protected-resource, dynamic client registration, PKCE (S256)
required, one-hour access tokens, refresh tokens that rotate on every use — a refresh token used twice
revokes the connection. Removing someone from a workspace also cuts off the apps they connected.
Self-hosted: the same tools ship in @vitrus-dev/mcp; mount it behind your own auth.
Tools#
Every tool is read-only and says so to the client (readOnlyHint). Ranges are
days or exact from/to dates.
| Tool | Returns |
|---|---|
list_sites | Sites you can read. |
get_overview | Visitors, sessions, pageviews, bounce, duration, channels, pages, referrers. |
query_stats | Any metric (visitors, sessions, pageviews, events) by any of 20 dimensions or by day, with filters. |
get_realtime | Who is on the site now, on which pages, from where. |
get_ai_traffic | AI referrals and AI crawlers, kept separate. |
get_revenue | Revenue, orders, AOV, conversion — per currency, never converted. |
list_goals · goal_report | Saved goals and their conversions; ad-hoc goals too. |
analyze_funnel | Ordered funnel; you can pass your own steps. |
get_journeys | The most common page paths, in order. |
get_retention | Cohort matrix, or the reason it is unavailable. |
get_lifecycle | Signed-in users of one site, counted: active, new, came back, lost, quick ratio, one-and-done, plans, became / stopped paying. |
get_portfolio | Every site you can read, side by side: visitors, active / new / lost users, signups, paying users, revenue per currency — ask “how are all my apps doing?”. |
get_web_vitals | Core Web Vitals (p75) and slowest pages. |
get_errors | JavaScript errors by message, page and browser. |
get_digest | The plain-language summary with evidence ids. |
get_tracking_snippet | The script tag, custom events, revenue and identify. |
Every answer carries its evidence#
This is the part that differs from other analytics MCP servers. Each metric comes back with the SQL that produced it, its parameters and the raw rows:
{
"metric": "visitors.unique",
"value": 40,
"query": "SELECT COUNT(DISTINCT visitor_id) ... bot_kind = ''",
"params": ["site-id", 1789003421000, 1789608221000],
"rows": [...]
}
A human reading a dashboard can sense when a number looks wrong. An agent cannot — it takes the number, writes it into a report, and the error propagates with full confidence. Returning the query lets the agent cite evidence, and lets you audit what it said afterwards.