MCP server - Docs

OakData ships a remote Model Context Protocol server at https://oakdata.co/api/mcp. Point an MCP-capable agent - Claude Code, Claude Desktop, Cursor, or your own - at it with a secret key, and the agent gets tools for reading real user behaviour: traffic overviews, visitor journeys, funnels, who's live right now, raw events, and session replays - all without leaving the editor.

Why this matters

The REST API is for code you write. The MCP server is for the agent itself: it can call get_journey to find where users drop off, then get_visitor to see one person end to end - in the flow of a conversation.

How it works

The server is a stateless JSON-RPC 2.0 endpoint over the MCP Streamable HTTP transport (protocol version 2025-06-18). Every request is authenticated with a secret key as a bearer token and scoped to exactly one project. It speaks the standard initialize, tools/list, tools/call, and ping methods - any compliant MCP client works.

Connecting

Fastest path: paste this prompt into the agent itself and let it wire up its own config, giving it your secret key when asked:

Connect with your AI agent

Paste into Claude Code, Cursor, or any agent in your repo

Connect yourself to our OakData analytics via its MCP server so you can read real user behaviour.

1
The server is https://oakdata.co/api/mcp (HTTP transport, stateless JSON-RPC). It authenticates with the header "Authorization: Bearer <my secret key, starts with oak_sec_>" - ask me for the key and store it in your client's secret config, never in a committed file.
2
If you are Claude Code, run: claude mcp add --transport http oakdata https://oakdata.co/api/mcp --header "Authorization: Bearer <key>". Otherwise, add an "oakdata" entry with that url and header to your client's mcpServers config (e.g. .cursor/mcp.json).
3
Verify the connection by calling the get_overview tool, then give me a short summary of the last 7 days of traffic.

Your agent will ask for your key.

Claude Code

Add the server with the CLI:

Terminal

bash

claude mcp add --transport http oakdata https://oakdata.co/api/mcp \
  --header "Authorization: Bearer oak_sec_xxxxxxxxxxxxxxxxxxxxxxxx"

Cursor & JSON-configured clients

Most clients (Cursor, Claude Desktop, Windsurf, …) take an mcpServers JSON block. Add OakData as an HTTP server with an Authorization header:

{
  "mcpServers": {
    "oakdata": {
      "url": "https://oakdata.co/api/mcp",
      "headers": {
        "Authorization": "Bearer oak_sec_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Use a secret key

The MCP server requires a secret key (oak_sec_…); public keys are rejected. Treat it like a password - store it in your client's secret config, not in a committed file.

Tools

Nine read tools, mapping one-to-one onto the REST API - the response shapes are the same.

Tool	Type	Description
`get_overview`	`range?, exclude_bots?`	Headline traffic & conversion for a window - visitors, pageviews, sessions, bounce, duration, and top pages/referrers/sources/campaigns/countries/browsers/devices. Start here.
`list_sessions`	`range?, limit?`	Recent sessions with visitor, entry page, duration, device, and location. limit 1–200, default 50.
`get_session`	`session_id`	The full ordered event timeline for one session - every pageview, click, and custom event with properties.
`get_visitor`	`distinct_id`	One visitor's full profile by distinct id or anonymous id: user id, traits, groups, first/last seen, lifetime events, recent sessions - including pre-signup activity.
`get_journey`	`range?`	The aggregated path/funnel tree for a window: common routes and where people drop off. Answers 'where are we losing people?'
`live_now`	`—`	Sessions active in the last 5 minutes, with ids and last-seen timestamps. A real-time pulse.
`list_events`	`offset?, limit?`	The raw event firehose, newest first, paginated. limit 1–500, default 100. For debugging tracking or inspecting custom properties.
`list_replays`	`limit?`	Recorded replays, newest first, with visitor, entry url, duration, device, and whether the session hit errors. limit 1–200, default 100.
`get_replay`	`replay_id`	One replay by its recording id: metadata plus short-lived signed URLs for each rrweb chunk a player can fetch and replay.

Valid range values: 24h, 7d, 30d, 90d (default 7d). Tool results come back as JSON text; tool-execution errors are reported in-band (with isError) so the agent can recover and try a different call.

Try it

Once connected, ask your agent things like:

prompts

text

"Use OakData - where are visitors dropping off in the signup funnel this week?"

"Pull up the last 10 sessions that hit an error and summarize what they were doing."

"Who's on the site right now, and what pages are they on?"

"Look up visitor user_8f3a and tell me their whole history."

Stateless & batchable

The server keeps no session state - each POST is authorized on its own. It accepts a single JSON-RPC message or a batch array (up to 50), and only answers POST (no server→client SSE stream).