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) and includeBots (default false, bots excluded).

Tool	Arguments	Returns
get_project	none	Name, trusted domains, retention, caps
get_overview	window, includeBots	Visitors, pageviews, bounce rate, visit duration
get_timeseries	window, includeBots	Visitors and pageviews over time
get_top_pages	window, includeBots	Most-visited paths
get_traffic_sources	window, includeBots	Search, social, direct, referral breakdown
get_countries	window, includeBots	Visitors by country
get_devices	window, includeBots	Browser, OS, device-type breakdowns
get_utm	window, includeBots	Campaign performance by UTM parameters
get_custom_events	window, includeBots	Counts per custom event name
get_goals	window, includeBots	Goal conversions and rates
get_realtime	none	Visitors active in the last 5 minutes
get_recent_sessions	window, includeBots, 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.