AI assistants (MCP) — Featherweight Analytics

ASK IT THINGS LIKE

“How did visitors trend over the last month?”

“What were my top pages last week, and where did that traffic come from?”

“Compare signup conversions on mobile vs desktop for June.”

The assistant translates questions like these into stats queries, reads the results, and answers in plain language — combining, comparing and summarising across as many queries as the question needs.

It is the same read-only engine behind your dashboard and the REST API: the same numbers, the same definitions, the same plan requirements. Nothing an assistant does through MCP can modify your sites or your data.

ENDPOINT & ACCESS

One endpoint, spoken over Streamable HTTP:

https://beta.featherweight.eu/mcp

Access is read-only, for sites on an upgraded plan — the same requirement as the REST API.

TWO WAYS TO CONNECT

WORKS WITHSIGN-IN

API key Claude Code, Cursor, and any MCP client that can send a header A key from Settings → API keys, sent as a Bearer header

OAuth claude.ai and the Claude desktop app Your normal Featherweight login, on a consent screen

WITH AN API KEY

Create a key in Settings → API keys (it’s shown once — copy it straight away). The key can read stats for any site in your account on an upgraded plan.

Claude Code

claude mcp add --transport http featherweight \
  https://beta.featherweight.eu/mcp \
  --header "Authorization: Bearer <your-token>"

Cursor (and most other clients with a JSON config)

{
  "mcpServers": {
    "featherweight": {
      "url": "https://beta.featherweight.eu/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Any MCP client that can send a custom header works the same way.

TIP

Treat the key like a password — don’t paste it into configuration you share or commit. If a key leaks, revoke it in Settings → API keys; connected clients stop working immediately.

WITH OAUTH (CLAUDE.AI AND CLAUDE DESKTOP)

No key to copy — you sign in instead:

Open the connector settings

In claude.ai (or the Claude desktop app), go to Settings → Connectors → Add custom connector.

Enter the endpoint

Use https://beta.featherweight.eu/mcp as the URL. No client ID or secret is needed.

Sign in and approve

You’re sent to Featherweight to sign in (if you aren’t already) and asked to approve the connection on a consent screen. Access is read-only and tied to your account.

Connections you approve appear under Settings → Connected apps in the Featherweight dashboard, with when they were connected and last used. One click disconnects an app and revokes its tokens — it would have to go through the consent screen again to reconnect.

OAuth sign-in currently supports Claude’s apps; for other MCP clients, use an API key as above.

WHAT THE ASSISTANT GETS

Two tools, mirroring the REST API:

TOOLDOES

list_sites Lists the sites the connection can read — each with its numeric id, domain, timezone, and an api_access flag saying whether its plan includes API access.

query_stats Runs one stats query: aggregate totals, a breakdown (top pages, sources, countries, goals, custom events, …), or a time series — with the same dimensions, metrics, filters and date presets as POST /stats/query.

Assistants are told how to use them — to start with list_sites, that dates are interpreted in the site’s timezone, and that error messages name the allowed values so a bad call can be corrected rather than retried blindly. You don’t need to explain any of that in your prompts.

GETTING GOOD ANSWERS

Name the site if your account has more than one (“…on example.com”), or the assistant will ask — or guess.
Be specific about the window (“last 30 days”, “June 1st to 15th”). Dates are interpreted in the site’s timezone, and presets like “the last 7 days” match what the dashboard shows.
Big questions are fine. “Which countries convert best?” takes several queries (a breakdown, goals, maybe filters) — the assistant chains them itself.
The numbers match the dashboard. Same engine, same definitions — so “visitors” is daily uniques here too, and you can check any answer against the dashboard for the same range.

PLAN REQUIREMENTS AND LIMITS

Querying a site needs an upgraded plan — the same api access as the REST API. Sites without it still appear in list_sites (with api_access: false), but queries against them return a plan-upgrade notice, which the assistant will relay.
Filters are a paid feature, exactly as in the REST API.
Rate limits are shared with the REST API: 120 requests per minute (per key for API keys, per user for OAuth connections). A long conversation full of stats questions stays well inside this; hitting the limit returns a retry-after notice the assistant can honour.

SECURITY AND PRIVACY

Read-only, always. There are no writing tools — an assistant cannot create, change or delete anything through this connection.
Scoped to your account. A connection sees only your account’s sites; asking about anyone else’s returns not-found.
Nothing personal to leak. Featherweight stores no personal data about your visitors, so there is none to expose here — stats are aggregates.
Revocation is immediate. Revoke an API key (Settings → API keys) or disconnect an app (Settings → Connected apps) and its access ends on the spot.

TROUBLESHOOTING

SYMPTOMLIKELY CAUSE

The connector won’t add, or every call is unauthenticated Wrong or revoked key; make sure the header is exactly Authorization: Bearer <token>. For OAuth, reconnect from the client’s connector settings.

“This site’s plan doesn’t include API access” The queried site isn’t on an upgraded plan — list_sites shows which sites are (api_access).

The assistant can’t find a site It’s not in the connected account — check which account you signed in with, or which account’s key you used.

“Stats backend temporarily unavailable” A brief backend outage; data collection is unaffected. Ask again in a minute.

BACK TO Documentation home

FOR AI ASSISTANTS