Convalytics MCP server

Read-only analytics for AI assistants via Model Context Protocol. Ask Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP-capable client questions about your Convalytics data in natural language:"what are my top pages this week," "how many signups in the last 24 hours," "show me the last ten payment_succeeded events."

Endpoint

POST https://api.convalytics.dev/mcp

JSON-RPC 2.0. Auth via Authorization: Bearer cnv_... using an API token generated at /tokens in the dashboard.

Plan requirement

Convalytics MCP is available on the Solo plan ($29/mo) and Pro plan ($99/mo). API tokens themselves can be generated on any plan, but the /mcp endpoint returns 402 plan_required for Free-tier tokens. Upgrade at convalytics.dev/billing.

Install in Claude Code

claude mcp add --transport http convalytics https://api.convalytics.dev/mcp \
  --header "Authorization: Bearer $CONVALYTICS_TOKEN"

Install in Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "convalytics": {
      "url": "https://api.convalytics.dev/mcp",
      "headers": {
        "Authorization": "Bearer cnv_..."
      }
    }
  }
}

Install in Cursor / Windsurf

Both follow the same JSON shape in their MCP settings. Add a new server with URL https://api.convalytics.dev/mcp and an Authorization: Bearer cnv_... header.

Token scope

Each API token is scoped to one team, not one project. A token grants read access to every project on the team it was created for. The four project-scoped tools below all take a project argument (name or id) so the agent picks which project to query on each call. Use list_projects first if you're not sure what's available.

Tools exposed

  • list_projects: all projects on the token's team (id, name, writeKey, site URL, deployment slug). Team-scoped, no arguments.
  • get_usage: current month's custom-event count, monthly quota, retention days, and plan name for the team. Team-scoped, no arguments.
  • top_pages(project, since?, until?, limit?): pages ranked by views in a time window, with unique visitors and share of total. Default window: last 7 days. Max 50 results.
  • top_referrers(project, since?, until?, limit?): referring hosts ranked by visits, includes (direct). Default window: last 7 days.
  • pageviews_count(project, since?, until?): total page views and unique visitors in a window. The right tool for "how much web traffic did I get" questions. Page views live in a separate table from custom events.
  • events_count(project, name?, since?, until?): count of custom events (emitted via analytics.track()), optionally filtered by event name. Does not cover page views — use pageviews_count for those.
  • recent_events(project, name?, limit?, redact?, user?): most recent events, optionally filtered by name and/or user. userEmail, userName, and props are redacted by default; pass redact: false to include them.
  • user_activity(project, user, since?, until?): composite per-user snapshot — identity block (userEmail, userName, firstSeen, lastSeen), totals for pageviews and events, top pages visited, top event names, and the 20 most recent events with props. user accepts userEmail (case-insensitive) or visitorId. Use this for "how is dancleary@example.com using my app?" questions — one call, full picture.
  • weekly_digest(project, days?, compare?): one composite snapshot of a project's web analytics. Returns visitors, pageviews, sessions, bounce rate, avg session duration, top 5 pages, top 5 referrers, total custom events, top 5 event names, plus period-over-period deltas against the prior equal-length window. Default days: 7, compare: true. Use this instead of chaining top_pages + top_referrers + events_count when the agent just wants to report on a window.

project accepts either the project's case-insensitive name (e.g. "slopbench") or its id from list_projects.

Rate limits and errors

  • 120 requests per minute per token. Exceeding returns 429 rate_limit_exceeded with a Retry-After header and a resetAt timestamp.
  • 401 invalid_token for missing, malformed, or revoked tokens.
  • 402 plan_required for Free-plan teams.
  • JSON-RPC protocol errors (parse, invalid request, method not found) are returned in the standard JSON-RPC 2.0 error shape with the appropriate code.

Not included in v1

No write or admin tools. No funnel tool until the dashboard ships funnel views. No OAuth flow (API token is the only auth in v1). No MCP Apps UI resources. If one of these matters to you, tell us.

Discovery