Connect MCP — TopStat for AI agents

One endpoint, seven tools

TopStat exposes a standard MCP server over HTTP (JSON-RPC 2.0). Point any MCP client at the URL below — or run npx topstat-mcp locally with zero dependencies.

MCP endpoint

https://topstat.top/api/mcp

Authentication: use a TopStat API key (tsk_…) from the dashboard as a Bearer token, sign in to TopStat in your browser for session-based access, or use a read-only token from one of your public share links.

Connect in 3 steps

Works with every MCP-capable client. Pick your tool below and paste the config.

Get an API key

In the dashboard, open Public API and create a key with the reports scope. A read-only token from your public share links also works; signed-in browser sessions are supported too.

Add the server

Paste the config into Cursor, Claude Code, Codex or any MCP client. Replace YOUR_TOKEN with the token from step 1.

Ask questions

In your editor or terminal, ask things like “How is traffic this week vs last week?” — the agent calls TopStat tools and answers with real numbers.

Official npm package — works with any MCP client

# quick test in your terminal
TOPSTAT_API_KEY="tsk_..." npx -y topstat-mcp

Client config (stdio)

{
  "mcpServers": {
    "topstat": {
      "command": "npx",
      "args": ["-y", "topstat-mcp"],
      "env": { "TOPSTAT_API_KEY": "YOUR_API_KEY" }
    }
  }
}

The official stdio bridge runs locally and forwards requests to https://topstat.top/api/mcp with your API key. Zero dependencies — Node 18+.

.cursor/mcp.json

{
  "mcpServers": {
    "topstat": {
      "url": "https://topstat.top/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Terminal

claude mcp add --transport http topstat \
  https://topstat.top/api/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

~/.codex/config.toml

[mcp_servers.topstat]
url = "https://topstat.top/api/mcp"
http_headers = { Authorization = "Bearer YOUR_TOKEN" }

Settings → Connectors → Add custom connector

https://topstat.top/api/mcp

Claude Desktop connects to remote MCP servers via custom connectors. Add the URL above, then sign in to TopStat in your browser so the session cookie can be used.

What your AI agent can do

Seven tools are exposed over MCP — everything needed for day-to-day analytics questions.

Tool	What it returns
`topstat_list_sites`	All websites tracked in your account, with event counts.
`topstat_get_stats`	Visitors, pageviews, channels, countries, devices and top pages for a period.
`topstat_get_funnels`	Funnels with step-by-step conversion analysis.
`topstat_get_revenue`	Revenue totals and attribution by channel and country.
`topstat_get_journey`	A visitor's pageview replay, or the most active sessions.
`topstat_get_realtime`	Visitors online right now and per-minute pageviews for the last 30 minutes.
`topstat_list_alerts`	Traffic alert rules with metric, threshold, window and last fired time.

How is traffic this week compared to last week?

Which channel brings the most paying customers?

Where do my buyers come from and what devices do they use?

Summarize funnel conversion for the last 30 days.