> ## Documentation Index
> Fetch the complete documentation index at: https://learn.kubit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools Reference

> Reference for the 15 Kubit MCP server tools: what each one does, its inputs, the report types it builds and its limits.

This page covers the tools the Kubit MCP server exposes, their inputs, the report types `create_report` builds, workspace context, cached results and limits. Your assistant calls these tools for you. The parameter names matter when you build your own MCP client or read a tool call in your assistant's log.

## When to use

| **Use case** | **Example** |
| - | - |
| Check what a tool can do before you prompt | Can the MCP server build a Data Table report? |
| Read a tool call in your assistant's log | Why did `get_report` return the cached result? |
| Build your own MCP client or agent on Kubit | Which tools need `wsctx`? |

## Tools

The Kubit MCP server has 15 tools. Every tool except `init` and `switch` needs a `wsctx` workspace token. [Workspace context](#workspace-context) explains it. Every client gets all 15 tools. A tool your workspace or organization can't use returns an error when called.

| **Tool** | **What it does** | **Inputs** |
| - | - | - |
| `init` | Starts a session. Returns your organization, workspace, schema, the available trace names (or events, in a workspace without traces) and Lumos memory, plus a `wsctx` token. Call it first. | None |
| `switch` | Changes the organization and workspace. Returns a new `wsctx` token that replaces the old one. | `orgId` (**Required**), `workspaceId` (**Required**) |
| `get_analytics_schema` | Returns every event, field and subject in the workspace with types and example values, plus its event tags and published filters, measures and binnings | None |
| `get_report_instructions` | Returns the rules and JSON Schemas for writing one kind of report as JSON. The assistant calls it before writing a report of that kind, and again after `switch`. | `kind` (**Required**) |
| `create_report` | Runs a report the assistant wrote as JSON, saves it in the workspace and returns the results with a link to the report in Kubit | `kind` (**Required**), `definition` (**Required**), `cohorts`, `basedOnReportId` |
| `get_report` | Opens a report by ID, searches reports by name, or lists your 10 most recent reports. A report opened by ID comes back with a sample of its rows and its definition as JSON. With `refresh`, runs the report again on current data. | `reportId`, `searchTerm`, `refresh`, `rows`, `where`, `columns` (all optional). `reportId` and `searchTerm` can't be used together. `refresh`, `rows`, `where` and `columns` work only with `reportId`. |
| `define_cohort` | Creates cohorts that later reports in the session use. These cohorts aren't published and don't show in the Kubit app. | `cohorts` (**Required**, at least 1) |
| `search_published_cohorts` | Finds published cohorts by part of their name or description | `term` (**Required**) |
| `explain_field` | Describes a field (type, description and its most frequent values), or finds the field that holds a value. The value search tolerates typos. | `field`, `term` (at least one) |
| `publish_component` | Publishes part of a report that already ran as a reusable component | `reportId` (**Required**), `kind` (**Required**), `name` (**Required**), `selector`, `description` |
| `import_dashboard` | Creates a new Kubit dashboard from a dashboard built in Claude, one tile per Kubit report | `name` (**Required**), `tiles` (**Required**), `description` |
| `workspace_create` | Creates a workspace in the current organization, sets up its storage and mints an API key. Returns a `wsctx` token for the new workspace. | `name` (**Required**), `description`, `timezone`, `pipelineType` |
| `workspace_mint_key` | Mints a new API key for sending traces to the current workspace | `note` (**Required**) |
| `memory` | Reads or changes Lumos memory. The workspace store holds facts about the workspace's data that every member's sessions use. The user store holds how you want results. | `action` (**Required**), `target`, `operations` |
| `help` | Sends a bug report, feedback or question to Kubit support, with your conversation as context, and waits briefly for a reply | `requestType` (**Required**), `text` (**Required**), `isUrgent` |

### Tool Inputs

<table>
  <colgroup>
    <col width="134" />

    <col width="180" />

    <col width="482" />
  </colgroup>

  <thead>
    <tr>
      <th>**Input**</th>
      <th>**Tool**</th>
      <th>**Values**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`kind`</td>
      <td>`create_report`, `get_report_instructions`</td>
      <td>`query`, `dataTable`, `funnel`, `path`, `activity`, `grid`, `agentFlow`, `retention`, `inspection` or `significance`. `get_report_instructions` also takes `cohort`. [Report types](#report-types) explains each.</td>
    </tr>

    <tr>
      <td>`definition`</td>
      <td>`create_report`</td>
      <td>The report as JSON, following the schema `get_report_instructions` returns for its kind</td>
    </tr>

    <tr>
      <td>`cohorts`</td>
      <td>`create_report`</td>
      <td>Cohorts that only this report uses, each under a key the assistant chooses. The result gives each cohort's ID for later reports.</td>
    </tr>

    <tr>
      <td>`basedOnReportId`</td>
      <td>`create_report`</td>
      <td>The ID of a report to change. The new report keeps that report's chart settings and becomes its next version. It has to be the same kind.</td>
    </tr>

    <tr>
      <td>`rows`</td>
      <td>`get_report`</td>
      <td>Reads a page of the report's rows instead of its summary: `offset` (default 0) and `limit` (default 50, at most 100)</td>
    </tr>

    <tr>
      <td>`where`, `columns`</td>
      <td>`get_report`</td>
      <td>`where` keeps only rows whose column equals a value or one of a list of values, such as `{ "Series": "Germany" }`. `columns` returns only the named columns, in that order. Neither works on a grid.</td>
    </tr>

    <tr>
      <td>`kind`</td>
      <td>`publish_component`</td>
      <td>`FILTER`, `MEASURE`, `VIRTUAL_EVENT`, `BINNING` or `COHORT`</td>
    </tr>

    <tr>
      <td>`selector`</td>
      <td>`publish_component`</td>
      <td>Which candidate to publish when the report has several: a measure variable such as `A`, a binning's field name, a cohort segment's name, or `FILTER` for the report's cohort filter</td>
    </tr>

    <tr>
      <td>`name`</td>
      <td>`publish_component`</td>
      <td>A new name creates a component. A name that holds the same definition returns that component unchanged. A name that holds a different definition adds a new version to it.</td>
    </tr>

    <tr>
      <td>`pipelineType`</td>
      <td>`workspace_create`</td>
      <td>`AGENT` (default) for agent traces, or `BEHAVIOR` for product events. Set at creation and can't be changed. `BEHAVIOR` has to be turned on for your organization.</td>
    </tr>

    <tr>
      <td>`action`, `target`</td>
      <td>`memory`</td>
      <td>`read` returns both stores. `update` changes one store, named in `target` as `workspace` or `user`. `init` and `switch` already return both stores.</td>
    </tr>

    <tr>
      <td>`operations`</td>
      <td>`memory`</td>
      <td>1 to 10 changes, each `add`, `patch` or `remove`, applied together or not at all. `patch` and `remove` find the entry by a unique part of its text. An entry marked `[locked]` was set by a person in Kubit and can't be changed.</td>
    </tr>

    <tr>
      <td>`requestType`</td>
      <td>`help`</td>
      <td>`BUG`, `FEEDBACK` or `QUESTION`. `isUrgent` applies to `BUG` only.</td>
    </tr>

    <tr>
      <td>`tiles`</td>
      <td>`import_dashboard`</td>
      <td>1 to 20 tiles in display order, each a `reportId` and an optional `title`</td>
    </tr>
  </tbody>
</table>

### Example Prompts

> "Which field holds the value gpt-4o-mini?"

> "Publish this report's filter as Production Traffic"

> "Remember that our production traffic is environment = prod"

## Report Types

The assistant picks the report kind and writes the report as JSON. It reads the kind's rules with `get_report_instructions` first, then sends the report to `create_report`. `create_report` builds 10 kinds:

| **Report type** | **`kind`** | **Builds when you ask for** |
| - | - | - |
| [Query](https://learn.kubit.ai/product-analytics/reports/query.md) | `query` | Counts, sums, rates, trends and breakdowns, or one value per group over the date range |
| [Data Table](https://learn.kubit.ai/product-analytics/reports/data-table.md) | `dataTable` | Several metrics as side-by-side columns per group, when you ask for a data table or for such columns |
| [Funnel](https://learn.kubit.ai/product-analytics/reports/funnel.md) | `funnel` | Conversion through an ordered sequence of steps |
| [Path](https://learn.kubit.ai/product-analytics/reports/path.md) | `path` | The event sequences after a start event or before an end event |
| Activity or Grid | `activity`, `grid` | Raw rows: whether an event arrives, what a field holds, what one trace, user or session did, or a list of users or sessions. `activity` is for a workspace with an Activity profile, `grid` for any other. Neither aggregates or trends. A grid can group its events by up to 2 fields. These are the only kinds whose date range can be shorter than a day. |
| Agent flow | `agentFlow` | Span labels, tool calls and model calls inside agent traces, drawn over whole traces |
| [Retention](https://learn.kubit.ai/product-analytics/reports/retention.md) | `retention` | Who comes back, period by period, and how often subjects return |
| Inspection | `inspection` | The members of one or more [cohorts](https://learn.kubit.ai/product-analytics/reports/cohorts.md) as rows, or a comparison of cohorts that names no metric |
| [Significance](https://learn.kubit.ai/product-analytics/reports/significance.md) | `significance` | Whether a difference between groups or experiment variants is beyond chance |

**Availability:** Significance reports need the Significance feature for your organization. Without it, `create_report` returns `Significance reports are not enabled for this organization.` A workspace that can't draw an Agent flow report returns `This workspace cannot draw an Agent Flow report.`

When the server rejects a definition, `create_report` returns the errors without running the report. The assistant fixes the definition and calls `create_report` again. The server doesn't retry on its own.

If the same definition ran in the last 6 hours, `create_report` reuses that data instead of querying again, and the result says when the data was computed.

To change a report, the assistant opens it with `get_report`, edits the definition JSON it returns and sends the result to `create_report` with `basedOnReportId`.

### Example Prompts

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

> "Show the agent flow across our traces over the last 14 days"

> "List the traces with an Exception in the last hour"

## Workspace Context

Every Kubit MCP session works in one organization and workspace. `init` picks your last-used workspace and returns a `wsctx` token for it. The assistant passes the token on every later tool call.

<table>
  <colgroup>
    <col width="240" />

    <col width="455" />
  </colgroup>

  <thead>
    <tr>
      <th>**Behavior**</th>
      <th>**Details**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Where the token comes from</td>
      <td>`init`, `switch` or `workspace_create`</td>
    </tr>

    <tr>
      <td>Changing workspace</td>
      <td>`switch` returns a new token. Use it on every later call.</td>
    </tr>

    <tr>
      <td>Expiry</td>
      <td>The token doesn't expire</td>
    </tr>

    <tr>
      <td>Lost access</td>
      <td>Kubit checks your access on every call. If you lose access to the workspace, calls fail until the assistant runs `init` or `switch`.</td>
    </tr>

    <tr>
      <td>Malformed or unknown token</td>
      <td>`Invalid session token. Call init to obtain a new one.`</td>
    </tr>
  </tbody>
</table>

### Example Prompts

> "Which Kubit workspace am I connected to?"

> "Switch to the staging workspace"

## Cached Results

`get_report` returns a report's last results when they're cached. The response says the data came from cache and gives the time it was cached. To get current data, ask the assistant to refresh the report. It calls `get_report` with `refresh` set, which runs the report again.

A refresh waits up to **50** seconds. If the report is still running after that, the response says so and tells the assistant to call `get_report` again later, without `refresh`.

### Example Prompts

> "Refresh the latency report"

> "Open the Weekly Performance report with today's data"

## Limits

<table>
  <colgroup>
    <col width="325" />

    <col width="419" />
  </colgroup>

  <thead>
    <tr>
      <th>**Constraint**</th>
      <th>**Value**</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Reports returned by a `get_report` search or recent list</td>
      <td>**10**</td>
    </tr>

    <tr>
      <td>Sample rows in a `create_report` result</td>
      <td>**20**</td>
    </tr>

    <tr>
      <td>Rows in one `get_report` page</td>
      <td>**50** by default, at most **100**</td>
    </tr>

    <tr>
      <td>Reuse of an identical `create_report` definition</td>
      <td>Data computed in the last **6** hours</td>
    </tr>

    <tr>
      <td>`get_report` refresh wait</td>
      <td>**50** seconds</td>
    </tr>

    <tr>
      <td>`help` wait for a support reply</td>
      <td>About **20** seconds. After that, the reply goes to your email.</td>
    </tr>

    <tr>
      <td>`import_dashboard` tiles</td>
      <td>**1** to **20**</td>
    </tr>

    <tr>
      <td>`import_dashboard` dashboard name</td>
      <td>**50** characters</td>
    </tr>

    <tr>
      <td>`import_dashboard` tile title</td>
      <td>**80** characters</td>
    </tr>

    <tr>
      <td>`publish_component` description</td>
      <td>**2,048** characters</td>
    </tr>

    <tr>
      <td>`workspace_mint_key` note</td>
      <td>**1** to **255** characters</td>
    </tr>

    <tr>
      <td>Lumos memory entry</td>
      <td>**300** characters</td>
    </tr>

    <tr>
      <td>`memory` changes per call</td>
      <td>**1** to **10**</td>
    </tr>

    <tr>
      <td>`workspace_mint_key` on an example workspace</td>
      <td>**Not supported**</td>
    </tr>

    <tr>
      <td>Deleting a published component</td>
      <td>**Not supported** through the MCP server. A published component is visible to everyone in the workspace.</td>
    </tr>
  </tbody>
</table>

## Related

* [Kubit MCP server](https://learn.kubit.ai/lumos-ai/mcp-server.md): what the server does and what it can't do.
* [Connect your AI assistant](https://learn.kubit.ai/lumos-ai/connect.md): setup for each client.
* [Import a dashboard from Claude](https://learn.kubit.ai/product-analytics/dashboards.md#import-a-dashboard-from-claude): what `import_dashboard` skips.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.