MCP server

CanaryLytics exposes a Model Context Protocol server at https://api.analytics.canarycoders.es/mcp, speaking streamable HTTP. Point an MCP client at it and the client’s model can read your traffic directly: every tool wraps the same query layer as the dashboard and /v1/stats, so the numbers can never diverge.

All tools are read-only. A read-only key (cly_read_…) gets the full surface, which makes it the right key to hand to an agent.

Connect a client

Any client that supports the streamable HTTP transport with custom headers works. Authentication is the same Bearer header as the REST API. Most JSON-configured clients accept this shape:

{
  "mcpServers": {
    "canarylytics": {
      "url": "https://api.analytics.canarycoders.es/mcp",
      "headers": { "Authorization": "Bearer cly_read_..." }
    }
  }
}

Note

Clients that only support OAuth for remote servers can’t send a static Bearer header. Use a client with header support, or bridge with a local proxy such as mcp-remote.

Authentication and limits

The Authorization: Bearer <key> header is required; without a valid key every request answers 401 unauthorized. Requests share the REST API’s read budget of 120 requests per minute per key, so a busy agent can hit 429 rate_limited with a Retry-After header. See Keys for how live and read-only keys relate.

The server is stateless: no session ids, no server-side conversation state, one self-contained JSON-RPC exchange per request.

Tools

Stats tools take window (24h, 7d, 30d, 90d; default 7d), includeBots (default false, bots excluded) and includeInternal (default false, self-declared internal traffic excluded). The table abbreviates that trio as filters.

Tool	Arguments	Returns
get_project	none	Name, trusted domains, retention, caps
get_overview	filters	Sessions, pageviews, bounce rate, segments, country/region/source breakdowns
get_timeseries	filters	Visitors and pageviews over time
get_top_pages	filters	Most-visited paths
get_traffic_sources	filters	Search, social, direct, referral breakdown
get_countries	filters	Visitors by country
get_locales	filters	Visitors by reported locale (page lang / browser language)
get_devices	filters	Browser, OS, device-type breakdowns
get_utm	filters	Campaign performance by UTM parameters
get_custom_events	filters	Counts per custom event name
get_goals	filters	Goal conversions and rates
get_realtime	none	Visitors active in the last 5 minutes
get_recent_sessions	filters, limit, offset	Paginated session list, newest first
get_session	sessionId	Full event trail of one session

Results come back as JSON in the tool’s text content, in the same shapes as the REST API responses.

Raw protocol example

The endpoint is plain JSON-RPC 2.0 over HTTP POST, so it is easy to probe without a client:

curl https://api.analytics.canarycoders.es/mcp \
  -H "Authorization: Bearer cly_read_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_overview","arguments":{"window":"30d"}}}'

Related

REST APIThe /v1 endpoints these tools wrap.

KeysLive vs read-only keys, rotation, and what each may do.