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

# Omneo Insights MCP Server

> Connect AI clients to Omneo Insights reporting data with the Omneo Insights MCP server.

Connect your AI client to Omneo Insights with the `omneo-insights` MCP server. The server gives supported AI tools access to reporting and analytics data for the tenant and permissions available to your Omneo Insights account.

<Info>
  The Omneo Insights MCP server does not bypass Omneo permissions. It can only return data from the tenant and reporting views you can access in the Omneo Insights web UI at `portal.insights.getomneo.com`.
</Info>

## Before you begin

You need access to [Omneo Insights](/experiences/omneo-insights/overview) and an AI client that supports remote MCP servers with OAuth.

Using an AI coding tool? Copy the following prompt to install the Omneo Insights skill and configure the MCP server.

<Prompt description="Install the Omneo Insights skill and configure the MCP server." actions={["copy"]}>
  Install the Omneo Insights skill.

  `npx skills add [https://docs.omneo.io/](https://docs.omneo.io/)`

  After the skill is installed, configure a remote MCP server named `omneo-insights` in my current AI client.

  Server URL: `https://portal.insights.getomneo.com/api/mcp`
  Authentication: OAuth

  Use the client's supported remote MCP setup flow. After the server is added, start the OAuth flow, authenticate with my Omneo Insights account, and verify that the server is connected. The server is tenant-specific and permission-based, so it can only return data from the tenant and reporting views I can access in the Omneo Insights web UI at `portal.insights.getomneo.com`.

  Use the `omneo-insights` skill whenever I ask about Omneo Insights analytics, reporting, customer data, Profiles, Transactions, Orders, retention, churn, lifetime value, segments, store performance, or saving analytical work as a Question or Dashboard.

  After connection, test with this prompt: "Show monthly active Profiles for the last 6 months and explain the largest month-on-month change."
</Prompt>

The skill gives your AI coding tool Omneo-specific guidance for discovering data, building valid queries, explaining results, and confirming before saving Questions or Dashboards.

## Server details

| Item           | Value                                          |
| -------------- | ---------------------------------------------- |
| Server name    | `omneo-insights`                               |
| Server URL     | `https://portal.insights.getomneo.com/api/mcp` |
| Authentication | OAuth                                          |
| Access model   | Tenant-specific and permission-based           |
| Web UI         | `https://portal.insights.getomneo.com`         |

## Neo AI and the MCP server

Neo AI and the Omneo Insights MCP server both help you work with reporting data using natural language, but they are used in different places.

**Neo AI** is the AI assistant inside Omneo Insights. It is available to all Omneo Insights users and is best when you are already working in the Insights web UI. Use Neo AI when you want to ask a reporting question, create or analyse a chart, inspect a result, or keep working inside Omneo Insights.

The **Omneo Insights MCP server** connects Omneo Insights to an external AI client, such as Claude, ChatGPT, Claude Code, or Codex. The AI runs in that external client, and the MCP server gives the client approved tools for finding reporting data, running queries, and creating saved reporting assets.

| Use Neo AI when                                                           | Use the MCP server when                                                             |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| You are already in Omneo Insights.                                        | You want to work from an external AI client.                                        |
| You want help exploring charts, tables, or saved questions in the web UI. | You want your AI client to query Omneo Insights alongside other work.               |
| You want to create or refine a chart without leaving Insights.            | You want to connect reporting data to a coding, analysis, or planning workflow.     |
| You want the AI experience managed inside Omneo Insights.                 | You want the external client to provide the AI model and call Omneo Insights tools. |

Both options use the permissions attached to your Omneo Insights account. You should review AI-generated queries, charts, and summaries before relying on them.

## Connect hosted AI clients

Hosted clients usually connect through account or workspace settings. Your workspace administrator may need to enable custom connectors or apps before individual users can authenticate.

### Claude web and Claude Desktop

<Steps>
  <Step title="Open connector settings">
    In Claude, open **Settings → Connectors**. For Team or Enterprise workspaces, an Owner may need to add the custom connector from organisation connector settings before members can connect.
  </Step>

  <Step title="Add a custom connector">
    Add a custom remote MCP connector with the URL `https://portal.insights.getomneo.com/api/mcp`.
  </Step>

  <Step title="Connect with OAuth">
    Select **Connect** for the custom connector and complete the OAuth flow with your Omneo Insights account.
  </Step>

  <Step title="Enable it in a conversation">
    In a Claude conversation, open the tools or connectors menu and enable the Omneo Insights connector before asking reporting questions.
  </Step>
</Steps>

### ChatGPT web and desktop

ChatGPT currently refers to custom MCP connectors as apps in developer mode. Some product surfaces and older references may still use connector language.

<Steps>
  <Step title="Enable developer mode">
    In ChatGPT web settings, go to **Settings → Apps → Advanced settings → Developer mode**. Availability depends on your ChatGPT plan and workspace settings.
  </Step>

  <Step title="Create an app from the MCP server">
    In **Apps** settings, create an app for the remote MCP server and enter `https://portal.insights.getomneo.com/api/mcp`.
  </Step>

  <Step title="Use OAuth authentication">
    Choose OAuth authentication when prompted, then complete the sign-in flow with your Omneo Insights account.
  </Step>

  <Step title="Select the app in chat">
    In a supported ChatGPT conversation, choose developer mode or apps from the composer and select the Omneo Insights app before asking reporting questions.
  </Step>
</Steps>

## Connect coding clients

Coding clients are configured from the command line. Use the server name `omneo-insights` so the tool names are easy to recognise in prompts and logs.

### Claude Code

Add the remote HTTP server:

```bash theme={null}
claude mcp add --transport http omneo-insights https://portal.insights.getomneo.com/api/mcp
```

In Claude Code, open the MCP menu and complete OAuth:

```text theme={null}
/mcp
```

After OAuth completes, list configured servers:

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

### Codex

Add the streamable HTTP server:

```bash theme={null}
codex mcp add omneo-insights --url https://portal.insights.getomneo.com/api/mcp
```

Start the OAuth flow:

```bash theme={null}
codex mcp login omneo-insights
```

Verify the server is configured:

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

## Available tools

The server exposes tools for discovering reporting data, running queries, and saving reporting assets.

| Capability   | Tools                                                                                    | What they enable                                                           |
| ------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Discovery    | `search`, `get_table`, `get_metric`, `get_table_field_values`, `get_metric_field_values` | Find available tables, metrics, fields, and useful values before querying. |
| Querying     | `construct_query`, `execute_query`, `query`                                              | Build and run structured reporting queries against Omneo Insights data.    |
| Saved assets | `create_question`, `create_dashboard`                                                    | Save reusable questions and dashboards in Omneo Insights.                  |

## Example prompts

Results depend on your tenant data and Omneo Insights permissions.

```text theme={null}
Show monthly active Profiles for the last 6 months and explain the largest month-on-month change.
```

```text theme={null}
Compare new Profile growth by channel for the previous quarter.
```

```text theme={null}
Show Reward issuance and redemption trends for the last 90 days, including unredeemed value by expiry month.
```

```text theme={null}
Break down Transactions and monthly active Profiles by location for the previous calendar month.
```

```text theme={null}
Which tiers have the highest Transaction frequency and average Transaction value?
```

```text theme={null}
Check whether Transaction data looks complete for the last 7 days and highlight gaps by channel or location.
```

```text theme={null}
Create a saved question that tracks tier distribution by month.
```

```text theme={null}
Create a dashboard for weekly incentive program performance, including Profile growth, Reward redemption, tier distribution, and Transaction value.
```

## Related concepts

* [Profile Aggregations](/concepts/profiles/aggregations): calculated Profile facts used in reporting
* [Transactions](/concepts/commerce/transactions): completed purchase and return records
* [Locations](/concepts/commerce/locations): store and location records used for reporting context
* [Rewards](/concepts/incentives/rewards): dollar-value incentives with issuance and redemption activity
* [Tiers](/concepts/incentives/tiers): status levels used in incentive program reporting