Skip to content

MCP server

The MCP server lets your coding agent answer questions about your analytics. It uses the same Query API as the dashboard, so your agent gets the same numbers you see. This page shows how to connect a client, how it authenticates, and which tools it can use.

Endpoint

  • The server is at https://app.nanolytics.dev/mcp and uses Streamable HTTP.
  • It's stateless: each request is handled on its own.
  • Every response includes a query_id and an as_of. Your agent should cite them alongside the numbers it gives you.

Authentication

A client can connect in one of two ways.

OAuthA site's secret key
How it worksThe client opens a browser, and you sign in and choose the organizationThe client sends Authorization: Bearer sk_… with every request
AccessEvery site in your organizationThat one site
ToolsAll of themAll except create_site and create_key
Best forWorking across sites, or adding new onesAn agent that installed nanolytics on one project (see Install)

The OAuth server's metadata is at https://app.nanolytics.dev/.well-known/oauth-protected-resource/mcp. Clients that support MCP's OAuth find it automatically.

You can get a secret key from the connect flow, from Settings → API keys, or with the create_key tool. Keep it out of your repository: it can read and write the site's data until you revoke it.

Claude Code

To connect with OAuth:

claude mcp add --transport http nanolytics https://app.nanolytics.dev/mcp

To connect with a site's secret key, read it from .env.local so the key never appears in the command:

claude mcp add --transport http --scope local nanolytics https://app.nanolytics.dev/mcp --header "Authorization: Bearer $(grep '^NANOLYTICS_KEY=' .env.local | cut -d= -f2-)"

--scope local keeps the server configured for this project on your machine only, so it isn't committed to the repository. The tools are available from your next session.

Other clients

For clients that take an mcpServers entry and read the key from the environment, use this config and set NANOLYTICS_KEY to the site's secret key:

{
  "mcpServers": {
    "nanolytics": {
      "type": "http",
      "url": "https://app.nanolytics.dev/mcp",
      "headers": { "Authorization": "Bearer ${NANOLYTICS_KEY}" }
    }
  }
}

If your client supports MCP's OAuth, all it needs is the URL: https://app.nanolytics.dev/mcp.

Typical workflow

  1. Call list_sites to get the sites you can read, with each one's ID, domain and timezone.
  2. Call get_schema for a site to see its first day of data, its dimensions, metrics and goals, and its event names with their property keys. Your agent should read this before writing a query.
  3. Ask with query. For ordered steps use funnel, for where people went from a step use paths, for one error group use error, and for recorded sessions use replays and replay.

To install on a new site, call create_site, add its snippet to your pages, then check it with install_status. To track more (page speed, errors, session replay, outbound links), use update_site. After the first line of code, neither needs any further code change.

Tools

ToolDescription
list_sitesThe sites you can read: each one's ID, domain and timezone.
get_schemaWhat a site has to ask about: its first day with data and today (in the site's timezone), the dimensions with their cardinalities, the metrics, its goals, and the event names with each one's property keys and how many values each takes.
queryRuns a query on the site's analytics through the public Query API, the same one the dashboard uses.
funnelOf the visitors who did the first step, how many then did each next step, in order, within a window of the first, and how soon (the median time from step 1).
pathsFrom one step, where people went next (direction after), a few steps deep, or how they arrived at it (before).
errorOne error group in a range: where it is thrown (call sites: each occurrence's top frame on the site's own host, by occurrences), in which releases, and its latest 10 occurrences with their page, browser, release, message as sent and stack frames.
replaysRecorded sessions (session replay), newest first, when the schema's has_replays is true: each one's start_ms (epoch milliseconds), duration_ms (how long its replay runs), pages (its pages in order, at most 20), pageviews, country, browser, os, device, errors (occurrences), replay (a link to watch it in the dashboard), and recording and date for the replay tool, which reads what happened in it.
replayWhat happened in one recorded session, without watching it: the session as replays lists it, where it came from (source, channel, referrer_host), and its events in order (up to 1,000), each at_ms after the session started.
create_siteAdds a site to your organization, or returns the one it already has for that domain: its ID, the snippet to put in every page's <head>, and how to check the install before deploying. Signed in with OAuth only.
install_statusWhether a site's tracker is reporting: the first and last hit (bots included, since a headless browser's hits are stored as a bot's), pageviews today, hits dropped in the last hour by reason, and what the tracker collects (update_site changes it).
update_siteChanges what a site's tracker collects, with no change to its tag or any code: the site's script carries its settings, and visitors get a change within five minutes.
create_keyMakes a secret API key for a site, for the Events API (server-side events) or the Query API, and returns it once: only its hash is kept. Signed in with OAuth only.
create_goalAdds a goal: a named predicate over a custom event's name or a page path (* matches any run of characters, as /blog/*).
delete_goalRemoves a goal by name.

Example questions

QuestionTool
What changed this month?query with "compare": "previous"
Where do visitors come from?query with a breakdown by source
Which pages are slow on phones?query with lcp_p75 by route, filtered on device
What broke since the last deploy?query with errors by error_group, ordered by first, then error for one group
How many people who saw pricing signed up within a day?funnel with a page step and an event step, "window": "1d"
Where do people go after the docs?paths with at on the page
Show me sessions that hit an errorreplays with a filter on error_group, then replay for one
Is the script working?install_status
Turn on page speedupdate_site with vitals on
Count signups as a goalcreate_goal with event_name

Goals apply to all the data you've already collected. Settings you change with update_site reach visitors within five minutes.

Same numbers as the dashboard

The dashboard and the Query API use the same engine, so a number from MCP matches the dashboard for the same range and filters.