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

# Nebuly MCP Server

> Connect AI assistants to Nebuly analytics through the Model Context Protocol

The Nebuly MCP Server lets AI assistants query Nebuly data through the [Model Context Protocol](https://modelcontextprotocol.io/).
Use it to ask questions about interactions, conversations, aggregated data or to export interaction CSV files without leaving your assistant.

<Note>
  The Nebuly MCP Server is currently in beta and available to all SaaS users and self-hosted customers.

  SaaS users can connect directly using `https://mcp.nebuly.com/mcp`.

  Self-hosted customers should use the URL provided by the Nebuly team.
</Note>

## Prerequisites

Before you configure the integration, make sure you have:

* A Nebuly account with MCP access (all SaaS users, or a self-hosted environment with MCP beta enabled).
* Your Nebuly MCP server URL, shown below as `<NEBULY_MCP_URL>`. SaaS users should use `https://mcp.nebuly.com/mcp`.
* One of the supported MCP clients: Claude Desktop, Claude Code, or Cursor.

## Configure your MCP client

<Tabs>
  <Tab title="Claude Desktop">
    Detailed instructions for adding the Nebuly MCP server to Claude Desktop can be found in the [Claude Desktop documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

    This typically requires organization-level configuration, so please reach out to your Claude administrator if you don't have access to the settings described in the documentation.
  </Tab>

  <Tab title="Claude Code">
    To install mcp servers in claude code it's required to have the [claude cli](https://code.claude.com/docs/en/quickstart/) installed.

    Add the Nebuly MCP server from your terminal:

    ```bash theme={null}
    claude mcp add --scope user --transport http nebuly-mcp <NEBULY_MCP_URL>
    ```

    Verify the server is available:

    ```bash theme={null}
    claude mcp list
    ```

    Other relevant instructions for managing MCP servers in Claude Code can be found in the [Claude Code documentation](https://code.claude.com/docs/en/mcp).
  </Tab>

  <Tab title="Cursor">
    Create or update your Cursor MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "nebuly-mcp": {
          "url": "<NEBULY_MCP_URL>",
          "auth": {
            "scopes": ["mcp:read", "mcp:write", "offline_access"]
          }
        },
      }
    }
    ```

    You can add this configuration to your project-level `.cursor/mcp.json` file or to your global Cursor MCP settings.

    Other relevant instructions for managing MCP servers in Cursor can be found in the [Cursor documentation](https://cursor.com/docs/mcp).
  </Tab>
</Tabs>

## MCP Overview

Once connected, your assistant can use Nebuly tools to inspect and analyze data.

### Interactions and conversations

* `list_projects`: List the Nebuly projects your assistant can access.
* `get_interactions`: Query interactions in a project with filters. Results will be paginated and limited, this tool is designed for browsing and inspecting small sets of interactions, not for bulk data retrieval.
* `get_interaction_details`: Retrieve the full record for a single interaction, based on an interaction ID.
* `get_conversation_detail`: Fetch the full conversation history based on a conversation ID.

### Analytics

* `get_interaction_aggregates`: Group interactions by one dimension, such as topic, sentiment, user intent, language, feedback, risk type, or custom fields.
* `get_interaction_multi_aggregates`: Break down interactions across multiple dimensions, such as topic by sentiment or intent by feedback.
* `get_interaction_time_series`: Build trends over time with minute, hour, day, week, month, or year buckets.
* `describe_aggregate_schema`: Discover the supported filters, groupings, metrics, ordering fields, and time granularities.

<Note>
  The analytics tool gets best result when used from assistants that can handle tabular data and charts, such as Claude Desktop.
</Note>

### Exports

* `get_interactions_csv`: Start an async CSV export for a filtered set of interactions.
  By default the export will include timestamp, input and output. You can ask your assistant to include additional fields such as user, topic, sentiment or cost.
* `get_csv_export_status`: Poll the status of a running export job. Returns `pending`, `running`, `completed`, or `failed` with a progress percentage.
* `prepare_csv_download`: Once the export is complete, call this to obtain a time-limited download URL. The URL expires after 5 minutes.

<Note>
  The tools for CSV export work best from assistants that can handle file downloads, such as Cursor or Claude Code.
</Note>

## Example questions

After defining a project to work with, your assistant can answer a wide variety of
questions about your Nebuly data. Here are some examples to get you started:

Try asking your MCP-enabled assistant:

* "List the Nebuly projects I can access."
* "Show me the top 10 topics by interaction volume over the last 30 days for the `PROJECT_NAME` project."
* "Show me a chart of negative-sentiment interactions by topic and user intent for the last two weeks."
* "Show daily interaction volume and error-rate trends for the last quarter."
* "Which topics have the highest average latency this month?"
* "Export January interactions with timestamp, user, input, output, topic, sentiment, and cost. Rome timezone"

<Note>
  Not all clients have access to your current position, to ensure the same results shown in the Nebuly UI provide
  your location/timezone in the question.
</Note>

<Note>
  Your assistant may call `describe_aggregate_schema` before answering analytics questions. This helps it choose the right filters, metrics, and grouping dimensions for your Nebuly workspace.

  Your assistant may call `list_projects` to check which projects it can access and ask you to choose one before answering your question.
</Note>