MCP Server

Kitbase speaks MCP (Model Context Protocol) in two ways. Connect either one to claude.ai, Claude Code, Cursor, or any MCP-compatible client and ask questions about your traffic, events, users, sessions, AI visibility, and bot traffic in natural language.

	Remote server	Local server (`@kitbase/mcp`)
Runs	Hosted at `https://api.kitbase.dev/mcp` — nothing to install	On your machine via `npx -y @kitbase/mcp` (stdio)
Auth	OAuth sign-in or a private API key	Your `kitbase login` session, or `KITBASE_TOKEN` / `KITBASE_API_KEY`
Scope	Exactly one project per credential	Every organization and project your account can access
Extra tools	Funnels, journeys, retention, frustration signals, realtime	Org/project discovery, SDK keys, raw bot requests, AI citations & job history
Best for	claude.ai / Claude Desktop connectors, zero setup	CLI users, Claude Code, headless and self-hosted setups

No Dashboard Required

Once connected, your AI assistant can answer questions like "How many visitors are on the site right now?" or "Which domains does ChatGPT cite instead of us?" by querying Kitbase directly.

Remote Server

The remote MCP server is built into the Kitbase API — there is nothing to install or run.

https://api.kitbase.dev/mcp

Self-hosted deployments serve the same endpoint at https://<your-host>/api/mcp.

Authentication

The server accepts two kinds of credentials. Both are scoped to exactly one project, so tools never need an organization or project parameter.

Method	Best for	How
OAuth	claude.ai / Claude Desktop connectors	Add the server URL as a custom connector; a browser window asks you to sign in and pick the org + project to grant access to
Private API key	Cursor, headless clients	Send `Authorization: Bearer sk_kitbase_...` (or `X-API-Key`) with each request

WARNING

Private API keys (sk_kitbase_) are secret keys — not the public SDK token used in browser SDKs. Generate one in your Kitbase dashboard under Project Settings > API Keys.

Client Setup

claude.ai (web / desktop)

Go to Settings > Connectors > Add custom connector
Enter https://api.kitbase.dev/mcp
Complete the sign-in flow and choose the organization and project to connect

Claude Code

bash

claude mcp add --transport http kitbase https://api.kitbase.dev/mcp \
  --header "Authorization: Bearer sk_kitbase_your_key_here"

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

json

{
  "mcpServers": {
    "kitbase": {
      "url": "https://api.kitbase.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_kitbase_your_key_here"
      }
    }
  }
}

Other MCP Clients

The server speaks the standard MCP Streamable HTTP transport. Any client that supports remote MCP servers works — point it at the URL and supply either credential.

Available Tools

The server exposes 31 read-only tools across ten categories. No tool can modify data.

Unless noted otherwise, every tool accepts the standard date parameters described in Date Filtering: preset, from, to, and timezone.

Web Analytics

Tool	Description	Extra parameters
`get_web_summary`	Summary KPIs — visitors, pageviews, bounce rate, average duration	`filters`
`get_web_timeline`	Visitors/pageviews as a time series	`interval` (`hour`/`day`/`week`/`month`), `filters`
`get_web_breakdown`	Break down by dimension (`country`, `browser`, `os`, `device`, `page`, `referrer`, …)	`dimension` (required), `page`, `size`, `filters`
`compare_web_periods`	Compare a dimension across two arbitrary date ranges	`dimension`, `currentFrom`/`currentTo`, `previousFrom`/`previousTo` (all required), `limit`, `filters`

Custom Events

Tool	Description	Extra parameters
`list_events`	List raw tracked events	`event`, `channel`, `userId`, `filters`, `page`, `size`, `sort`
`get_event_stats`	Grouped event counts	`groupBy` (default `event`), `channel`
`get_event_timeline`	Event counts over time	`interval`, `event`
`get_event_breakdown`	Break events down by dimension	`dimension` (required), `limit`

Users

Tool	Description	Extra parameters
`list_users`	List/search aggregated user analytics	`type` (`all`/`identified`/`anonymous`), `search`, `filters`, `page`, `size`
`get_user_summary`	Comprehensive single-user summary	`userId` (required)
`get_user_activity`	Daily activity heatmap for one user	`userId` (required), `months` (default 4); no date params
`get_user_events`	Paginated event timeline for one user	`userId` (required), `page`, `size`; no date params

Sessions

Tool	Description	Extra parameters
`list_sessions`	List aggregated sessions	`search`, `filters`, `page`, `size`
`get_session_detail`	Single session details (metadata only)	`sessionId` (required); no date params
`get_session_events`	Events inside one session	`sessionId` (required), `page`, `size`; no date params

Funnels & Journeys

Tool	Description	Extra parameters
`analyze_funnel`	Ad-hoc funnel: conversion + drop-off per step	`steps` (required — ordered list of `{type, value, name?, filters?}`), `analysisMode` (`session`/`user`)
`analyze_journey`	Most common multi-step event sequences	`steps` (count, default 3), `limit` (default 100)

Frustration Signals

Tool	Description	Extra parameters
`get_frustration_signals`	Rage clicks and dead clicks, with top pages/elements	`limit`

Retention

Tool	Description	Extra parameters
`get_retention`	Cohort retention: visitors grouped by the week/month of their first visit, with the share still active in each following period	`interval` (`week` default, or `month`)

Cohorts are anchored to each visitor's first visit ever, not the first visit inside the requested window, so long-standing visitors are never counted as new. Offset 0 is the cohort itself (100%). The date range selects which cohorts are returned.

Realtime

Tool	Description	Extra parameters
`get_realtime_visitors`	Distinct visitors active right now	`windowMinutes` (1–60, default 5); no date params

AI Visibility

How often your brand appears in AI search answers (ChatGPT, Gemini, Perplexity, Claude), which domains those answers cite, and how you stack up against competitors.

Most of these tools accept a provider filter (ALL default, chatgpt, gemini, perplexity, claude) and a jobs parameter — how many of the most recent scan jobs to aggregate when no date window is given (default 10).

Tool	Description	Extra parameters
`list_ai_brands`	Configured brands (yours + competitors)	none
`list_ai_prompts`	Prompts tracked against AI search engines	none
`get_ai_visibility_series`	Visibility score over time	`provider`, `limit` (default 30)
`get_ai_visibility_domains`	Domains AI answers cite, ranked by citation share	`provider`, `jobs`, `limit` (default 25)
`get_ai_competitors`	Your brand vs competitors (mentions, sentiment)	`provider`, `jobs`, `limit`
`get_ai_share_of_voice`	Your share of all brand mentions over time	`provider`, `jobs`
`get_ai_prompts_breakdown`	Per-prompt: did the brand appear in each provider's answer	`jobs`

Bot & AI-Crawler Traffic

Which bots and AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Googlebot, …) hit your site, from where, and what they read.

Tool	Description	Extra parameters
`get_bot_timeline`	Bot requests over time, grouped by vendor	`interval`
`get_bot_countries`	Per-country bot traffic (requests + distinct bots)	`page`, `size` (default 8)
`get_top_bots`	Top bots ranked by request count	`size` (default 10)
`get_bot_top_paths`	Pages most requested by bots	`size` (default 10), `vendor` (e.g. `GPTBot`)

Common Parameters

Date Filtering

Most tools accept date filtering via either a preset or an explicit date range:

preset — one of last_30_minutes, last_hour, today, yesterday, last_7_days, last_30_days, this_month, this_year
from / to — explicit date range in YYYY-MM-DD format (inclusive)
timezone — timezone for date calculations, e.g. Africa/Cairo (default: UTC)

If both a preset and explicit dates are provided, the preset takes precedence.

For the AI visibility tools, omitting all date parameters aggregates the last jobs scan jobs instead of a time window.

Pagination

List tools support pagination with page (0-indexed) and size.

Filters

Web analytics and event tools support filters in the format dimension:operator:values:

"country:is:US,UK"
"browser:is:Chrome"
"page:contains:/blog"

Pass multiple filters as an array to combine them.

Example Prompts

Question	Tools Used
"How many visitors are on the site right now?"	`get_realtime_visitors`
"How many visitors did we get last week?"	`get_web_summary`
"Compare this week's traffic to last week by country"	`compare_web_periods`
"What's our weekly retention looking like this quarter?"	`get_retention`
"Show me the signup funnel conversion rate"	`analyze_funnel`
"How visible is our brand in AI search this month?"	`get_ai_visibility_series`
"Which domains does ChatGPT cite instead of us?"	`get_ai_visibility_domains`
"How do we compare to competitors in AI answers?"	`get_ai_competitors`
"Is ChatGPT crawling our docs? Which pages?"	`get_top_bots` + `get_bot_top_paths`
"Which pages have the most rage clicks this week?"	`get_frustration_signals`
"Show me a summary of user U-123's activity"	`get_user_summary`

Local Server (`@kitbase/mcp`)

@kitbase/mcp runs the MCP server on your machine over stdio — the standard transport for Claude Code, Claude Desktop, and the MCP Inspector. Instead of being locked to one project, it authenticates as you and can browse every organization and project your account can access.

Setup

bash

kitbase login
claude mcp add kitbase -- npx -y @kitbase/mcp

For Cursor or Claude Desktop, use a command-based server entry:

json

{
  "mcpServers": {
    "kitbase": {
      "command": "npx",
      "args": ["-y", "@kitbase/mcp"]
    }
  }
}

Authentication

The server resolves a token on the first tool call, in this order (first match wins):

KITBASE_TOKEN — an explicit user JWT (power users / CI)
KITBASE_API_KEY — a private API key (sk_kitbase_*), sent as-is
CLI credentials — ~/.config/kitbase/credentials.json from kitbase login, refreshed automatically when near expiry

Set KITBASE_API_URL to point the server at a self-hosted backend (default: https://api.kitbase.dev).

Start with discovery

Unlike the remote server, tools here are not pre-scoped to a project. Ask your assistant to call list_orgs_and_projects first — it returns the orgSlug and projectId values every other tool requires.

Available Tools

The server exposes 25 read-only tools across eight categories. No tool can modify data.

Every tool except list_orgs_and_projects requires orgSlug and projectId. Unless noted otherwise, tools also accept the standard date parameters described in Date Parameters: preset, from, to, and timezone.

Discovery

Tool	Description	Extra parameters
`list_orgs_and_projects`	List your organizations and each org's projects — call this first to get `orgSlug` + `projectId`	`orgSlug` (optional — limit to one org); no date params

Web Analytics

Tool	Description	Extra parameters
`web_analytics_summary`	Summary KPIs — visitors, sessions, pageviews, bounce rate, average duration, revenue, each vs the previous period	`filters`
`web_analytics_timeline`	Time-bucketed pageviews/sessions/visitors (current vs previous period); set `dimension` + `value` to drill into one value's timeline	`interval` (`minute`/`hour`/`day`, default `hour`), `dimension` + `value`, `filters`
`web_analytics_breakdown`	Top values for a dimension (`country`, `browser`, `path`, `referrer`, `utm_*`, `device`, …); use `page_duration` for top pages by average time spent	`dimension` (required), `page`, `size`, `filters`
`web_analytics_compare`	Compare a dimension across two explicit date ranges, biggest movers first	`dimension`, `currentFrom`/`currentTo`, `previousFrom`/`previousTo` (all required), `limit` (default 10), `filters`
`list_tracked_names`	Distinct page paths or custom event names seen in the project	`kind` (`paths`/`event_names`, required); no date params

Custom Events

Tool	Description	Extra parameters
`events_stats`	Total events, unique users, and a breakdown grouped by event name or user	`group_by` (`event`/`user`, default `event`), `channel`; no `preset`
`events_timeline`	Event counts over time	`interval` (`hour`/`day`/`week`/`month`, default `day`), `event`; no `preset`
`events_breakdown`	Events grouped by a dimension (event name, user, geo, browser, OS, device, UTM)	`dimension` (required), `limit` (default 20); no `preset`
`events_aggregations`	One row per unique event name: count, unique users, first/last seen, 24-hour sparkline	`channel`, `search`, `user_id`, `page`, `size`, `sort`
`list_events`	Raw custom events, paginated	`event`, `channel`, `user_id`, `filters`, `page`, `size`, `sort`

AI Visibility

Most of these tools accept a provider filter (ALL default, CHATGPT, GEMINI, PERPLEXITY, CLAUDE) and a jobs parameter — how many of the most recent completed analysis jobs to aggregate when no date window is given.

Tool	Description	Extra parameters
`ai_visibility_series`	Presence-rate time series, one point per completed job	`provider`, `limit`
`ai_visibility_share_of_voice`	Each tracked brand's share of voice and rank per job	`provider`, `jobs`
`ai_visibility_breakdown`	Presence and citation totals per AI provider	`jobs`
`ai_visibility_competitors`	All tracked brands ranked by visibility rate	`provider`, `jobs`, `limit`
`ai_visibility_citations`	Domains cited by AI answers; pass `domain` to drill into its cited URLs	`domain`, `provider`, `jobs`, `limit`, `page`, `size`
`ai_visibility_cited_pages`	Exact pages (URLs) cited across all domains, most-cited first; set `mentioningBrand: true` to only count citations from answers featuring your brand	`provider`, `mentioningBrand`, `jobs`, `page`, `size`
`ai_visibility_prompts`	Tracked prompts; set `includeBreakdown: true` for per-prompt presence metrics	`includeBreakdown`, `jobs`
`ai_visibility_jobs`	Analysis job history; pass `jobId` for one job's detail and live progress	`jobId`, `limit`; no date params

Bot & AI-Crawler Traffic

Tool	Description	Extra parameters
`bots_analytics`	Bot/crawler traffic — pick a `view`: top bots, top scraped paths, per-vendor timeline, or per-country breakdown	`view` (`top_bots`/`top_paths`/`timeline`/`countries`, required), `interval` (default `day`), `size` (default 10), `page`
`list_bot_requests`	Raw bot/crawler request log, paginated	`search`, `actorType` (`verified_bot`/`spoofed_bot`/`suspected_bot`), `page`, `size`

Sessions

Tool	Description	Extra parameters
`list_sessions`	Aggregated visitor sessions, paginated	`search`, `filters`, `page`, `size`
`get_session`	One session's detail; set `includeEvents: true` to also return its event stream	`sessionId` (required), `includeEvents`, `page`, `size`; no date params

Users

Tool	Description	Extra parameters
`list_analytics_users`	Aggregated analytics users, paginated	`type` (`all`/`identified`/`anonymous`), `search`, `filters`, `page`, `size`
`get_analytics_user`	One user's data — choose sections via `include`: `summary` (default), `activity` heatmap, `events`	`userId` (required), `include`, `months` (default 4), `page`, `size`; no date params

SDK Keys

Tool	Description	Extra parameters
`list_sdk_keys`	The project's public SDK keys (private API keys and secrets are never returned)	`page`, `size`, `sort`; no date params

Date Parameters

Date-scoped tools accept:

preset — one of last_30_minutes, last_hour, today, yesterday, last_7_days, last_30_days, this_month, this_year; overrides from/to when set
from / to — explicit date range in YYYY-MM-DD format (inclusive)
timezone — IANA timezone used to resolve date boundaries, e.g. America/New_York (default: UTC)

Pagination uses page (0-indexed, default 0) and size (1–100, default 20).

Filters take the format "dimension:operator:values" where the operator is is or is_not and values are comma-separated — e.g. ["country:is:US,UK", "browser:is_not:Safari"].

Example Prompts

Question	Tools Used
"Which Kitbase projects do I have access to?"	`list_orgs_and_projects`
"How did traffic on my docs project do this month vs last?"	`web_analytics_compare`
"What are the top pages people spend the most time on?"	`web_analytics_breakdown` (`page_duration`)
"Which custom events fired most this week?"	`events_aggregations`
"Which domains do AI answers cite, and which URLs on reddit.com?"	`ai_visibility_citations`
"What pages do AI engines cite when they mention my brand?"	`ai_visibility_cited_pages`
"Show me the raw GPTBot requests from today"	`list_bot_requests`
"What SDK keys does this project have?"	`list_sdk_keys`

Requirements

A Kitbase account with an active project
Remote server with API-key auth: a private API key (sk_kitbase_) from Project Settings > API Keys
Local server: Node.js 18+ and either a kitbase login session or a KITBASE_TOKEN / KITBASE_API_KEY environment variable

Next steps

CLI — the same operations from your terminal instead of an AI assistant, and where kitbase login lives.
API reference — the REST API behind every MCP tool.
Analytics dashboard guide — the data these tools query.

MCP Server ​

Remote Server ​

Authentication ​

Client Setup ​

claude.ai (web / desktop) ​

Claude Code ​

Cursor ​

Other MCP Clients ​

Available Tools ​

Web Analytics ​

Custom Events ​

Users ​

Sessions ​

Funnels & Journeys ​

Frustration Signals ​

Retention ​

Realtime ​

AI Visibility ​

Bot & AI-Crawler Traffic ​

Common Parameters ​

Date Filtering ​

Pagination ​

Filters ​

Example Prompts ​

Local Server (@kitbase/mcp) ​

Setup ​

Authentication ​

Available Tools ​

Discovery ​

Web Analytics ​

Custom Events ​

AI Visibility ​

Bot & AI-Crawler Traffic ​

Sessions ​

Users ​

SDK Keys ​

Date Parameters ​

Example Prompts ​

Requirements ​

Next steps ​

MCP Server

Remote Server

Authentication

Client Setup

claude.ai (web / desktop)

Claude Code

Cursor

Other MCP Clients

Available Tools

Web Analytics

Custom Events

Users

Sessions

Funnels & Journeys

Frustration Signals

Retention

Realtime

AI Visibility

Bot & AI-Crawler Traffic

Common Parameters

Date Filtering

Pagination

Filters

Example Prompts

Local Server (`@kitbase/mcp`)

Setup

Authentication

Available Tools

Discovery

Web Analytics

Custom Events

AI Visibility

Bot & AI-Crawler Traffic

Sessions

Users

SDK Keys

Date Parameters

Example Prompts

Requirements

Next steps