Kubit MCP Server

This guide covers how to connect to Kubit's MCP (Model Context Protocol) server, the available tools, authentication, and how to use Kubit's analytics capabilities from AI development tools.

What is the Kubit MCP Server?

The Kubit MCP server lets you interact with Kubit's analytics platform from AI tools like Claude Code and Cursor. Instead of opening the Kubit UI, you describe what you want in natural language — the MCP server translates your request into the appropriate report configuration, executes it, and returns results directly in your development environment.

The server is stateless and streams responses over HTTP using the MCP protocol.

Connecting to the MCP Server

Claude Code

Kubit provides a plugin for Claude Code that registers the MCP server automatically.

Install the Plugin

Run the following command in your terminal:

npx @kubit-ai/agent-plugin@latest

The installer registers the Kubit MCP server, adds the required skills, and configures authentication. Restart Claude Code after installation for the MCP connection to take effect.

Verify the Connection

After restarting, use the /kubit-connect command in Claude Code to initialize your session. This authenticates you, selects your organization and workspace, and loads your workspace schema.

Update the Plugin

npx @kubit-ai/agent-plugin@latest

Run the same install command to update to the latest version. The updater replaces all shipped skills and MCP configuration. Restart Claude Code after updating.

Cursor

1. Open Settings → Tools & MCP.

2. Click Add Custom Server.

3. Set the URL to https://mcp.kubit.ai/mcp using HTTP-stream transport.

4. Save and authenticate with your Kubit credentials when prompted.

Other MCP Clients

Any MCP-compatible client can connect to the Kubit server using:

Authentication

The MCP server uses Bearer token authentication. Your AI tool sends an Authorization: Bearer <token> header with every request. The token is the same credential used to access the Kubit web application — the MCP server forwards it to the backend, so you see the same data and permissions as you would in the UI.

Authentication is handled automatically by the plugin installer (Claude Code) or the MCP client's built-in OAuth flow (Cursor, Claude.ai). You do not need to manually manage tokens.

OAuth Flow (Cursor / Claude.ai)

When connecting from Cursor or Claude.ai, the MCP client initiates an OAuth2 authorization-code flow:

1. Your browser opens the Kubit consent screen.

2. Sign in with your Kubit credentials (if not already signed in).

3. Authorize the MCP client.

4. The browser redirects back to your AI tool with an authorization code, which is exchanged for a token.

After authorization, the token is cached by the MCP client — you do not need to re-authenticate on every request.

MCP Tools

The Kubit MCP server exposes the following tools. Each tool is called by the AI agent on your behalf based on your natural language request.

init

Initialize a session and load workspace context. This is the first tool called in every session — it authenticates you, resolves your organization and workspace, and returns your workspace schema (events, fields, subjects, measures).

The tool returns a session token (WSCTX) that is passed on every subsequent tool call to maintain context.

switch

Switch to a different organization or workspace within the same session. Returns a new session token bound to the selected workspace.

create_report

Create and execute a report from natural language. The tool:

1. Classifies your request into the appropriate report type (Query, Funnel, Flow, Retention, Data Table, Cohort).

2. Translates your natural language into a structured report definition.

3. Validates the definition against your workspace schema.

4. Executes the report and returns results.

If validation fails, the tool automatically retries with corrections (up to 3 attempts).

Returns both the report results and a link to view the report in the Kubit UI.

get_report

Fetch, search, or refresh existing reports. Three modes (mutually exclusive):

inspect

Run an ad-hoc data grid query from natural language. Similar to create_report but optimized for tabular data exploration — returns results as a downloadable CSV export.

workspace_create

Create a new workspace and initialize its data warehouse. Used during onboarding to set up a workspace for telemetry ingestion.

workspace_mint_key

Mint an API key for a workspace. The API key is used by the telemetry SDK to send trace data to Kubit.

help

Submit a support request or ask a question. Routes to the Kubit support team with context about your environment.

Workspace Context

Every tool call (except init) requires a workspace context token (WSCTX). This token is obtained from init and identifies your current organization and workspace.

• init returns a WSCTX token. The AI agent caches it for the session.

• switch returns a new WSCTX token when you change workspaces. The previous token is no longer valid.

• All other tools accept wsctx as a parameter to route the request to the correct workspace.

You do not need to manage this token manually — the AI agent handles it automatically.

Cached Data

When the MCP server returns report results, it may indicate that the data came from cache rather than a fresh computation. The response includes a cachedDataInfo field:

• null — the result was freshly computed.

• { cachedAt: <timestamp> } — the result came from cache. Use get_report with refresh: true to get fresh data.

Prompting Kubit Through MCP

You interact with Kubit by describing what you want in natural language. The MCP server handles classification, validation, and execution.

Effective Prompts

A good prompt specifies:

1. What you want to know — the question you're trying to answer

2. Report type (optional) — funnel, retention, flow, or let Kubit auto-detect

3. Measures — what to calculate (count, average, sum, etc.)

4. Date range — the time window

5. Breakdown (if needed) — how to segment the data

6. Filters (if needed) — conditions to narrow the data

Examples by Complexity

Simple — single measure:

"How many events happened this week?"

Medium — with breakdown and filters:

"Show me daily average latency by model name over the last 30 days, filtered to production"

Advanced — specific report type with multiple parameters:

"Build a funnel from user prompt → tool call → response, broken down by model, with a 1-hour conversion window, last 14 days"

Search and fetch:

"Find the Weekly Performance dashboard"

"Refresh the latency report"

Workspace management:

"Create a new workspace called 'Production Monitoring'"

"Switch to the staging workspace"

Tips

• You don't need to specify the report type — Kubit infers it from your question. "How do users flow from search to checkout?" automatically creates a Flow report.

• Breakdowns are inferred from "by [dimension]" (e.g., "by country", "by model name").

• Filters are inferred from "where", "filtered to", "only", and "excluding".

• Date ranges are inferred from natural phrases — "last 7 days", "this month", "since March 1st".

• Say "refresh" or "get fresh data" to re-execute a cached report.

• The MCP server returns a link to the Kubit UI for every report, so you can explore further in the browser.