Nebuly MCP Server - Documentation

The Nebuly MCP Server lets AI assistants query Nebuly data through the Model Context Protocol. Use it to ask questions about interactions, conversations, aggregated data or to export interaction CSV files without leaving your assistant.

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.

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

Claude Desktop
Claude Code
Cursor

Detailed instructions for adding the Nebuly MCP server to Claude Desktop can be found in the Claude Desktop documentation.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.

To install mcp servers in claude code it’s required to have the claude cli installed.Add the Nebuly MCP server from your terminal:

claude mcp add --scope user --transport http nebuly-mcp <NEBULY_MCP_URL>

Verify the server is available:

claude mcp list

Other relevant instructions for managing MCP servers in Claude Code can be found in the Claude Code documentation.

Create or update your Cursor MCP configuration:

{
  "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.

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. Provide timezone-aware date filters to slice the data for specific periods as not all assistants are aware of the current timezone (e.g. Give me daily interaction volume for the last 7 days based on Rome timezone).
describe_aggregate_schema: Discover the supported filters, groupings, metrics, ordering fields, and time granularities.

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

Exports

get_interactions_csv: Start a 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: Check whether a CSV export is pending, running, completed, or failed. Your assistant will poll this tool after starting an export and provide you with a download link when the export is ready.

The tools for CSV export works best from assistants that can handle file downloads, such as Cursor or Claude Code.

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.

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.”

Core concepts

Documentation Index

​Prerequisites

​Configure your MCP client

​MCP Overview

​Interactions and conversations

​Analytics

​Exports

​Example questions

Prerequisites

Configure your MCP client

MCP Overview

Interactions and conversations

Analytics

Exports

Example questions