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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/ai/mcp/claude-desktop",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Using the MCP Server in Claude Desktop

> Connect your Omni data to Claude Desktop with Omni's MCP Server.

Claude Desktop is the app version of Anthropic's AI assistant, Claude. Once successfully connected to Omni, you can interact with your Omni data right in the Claude Desktop interface.

**Looking for Claude Code?** Check out the [Claude Code guide](/ai/mcp/claude-code).

## Requirements

<Note>
  Every person who wants to use the MCP Server must complete the setup.
</Note>

To follow the steps in this guide, you'll need:

* The latest version of [Claude Desktop](https://claude.ai/download) installed
* **The MCP Server AI setting** enabled in your Omni instance. An Organization Admin can enable this setting by navigating to **Settings > AI > General**.
* **For API key setup only**: [npm and Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed. Check with:
  ```bash theme={null}
  node -v
  npm -v
  ```

## Setup

Choose your setup method. See the [MCP authentication guide](/ai/mcp/authentication) if you need help selecting a method.

<Tabs>
  <Tab title="Claude Connector (Recommended)">
    The official Omni connector for Claude provides the fastest setup experience with no manual configuration required.

    <Steps>
      <Step title="Install the connector">
        Visit the [Omni Analytics connector](https://claude.com/connectors/omni-analytics) page and click **Add to Claude** to install the connector.
      </Step>

      <Step title="Authorize the connection">
        1. Claude will redirect you to an Omni authorization page.
        2. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#personal-access-tokens-pat) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your Claude Desktop chats.

        In a chat, click the <Icon icon="plus" iconType="solid" /> (plus) icon, then **Connectors**. Your Omni MCP connection should be enabled:

        <img src="https://mintcdn.com/omni-e7402367/XIpn-9Hi2cNutp5u/ai/images/claude-mcp-in-chat.png?fit=max&auto=format&n=XIpn-9Hi2cNutp5u&q=85&s=725773ff48261499c426a664b82c12ed" alt="Claude Desktop chat with the Omni connector enabled" width="1018" height="863" data-path="ai/images/claude-mcp-in-chat.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Custom OAuth">
    OAuth provides streamlined setup without manually managing API keys. Use this method if you need to configure the connector manually.

    <Steps>
      <Step title="Open Claude Desktop settings">
        In Claude Desktop, navigate to **Settings > Connectors**.
      </Step>

      <Step title="Add a custom connector">
        Click **Add custom connector**.
      </Step>

      <Step title="Configure the connector">
        In the dialog that displays, fill in the following:

        * **Name** - Enter a name for the connector, such as `Omni`
        * **Remote MCP Server URL** - Paste the following URL:

          ```
          https://callbacks.omniapp.co/callback/mcp
          ```

        Your configuration should look like this:

        <img src="https://mintcdn.com/omni-e7402367/XIpn-9Hi2cNutp5u/ai/images/claude-custom-mcp-connector.png?fit=max&auto=format&n=XIpn-9Hi2cNutp5u&q=85&s=00544826401e317f9cfd8c4f4facc5fe" alt="Claude Desktop custom MCP connector configuration dialog" width="1022" height="865" data-path="ai/images/claude-custom-mcp-connector.png" />

        Click **Add** to create the connector.
      </Step>

      <Step title="Authorize the connection">
        Claude Desktop will add the connector to the connector list.

        1. Click the **Connect** button next to the Omni connector you just created.
        2. Your browser will open and redirect you to an Omni authorization page.
        3. Review the requested permissions and click **Authorize**.

        Omni will automatically create a [Personal access token](/api/authentication#personal-access-tokens-pat) and link it to your Omni user account.
      </Step>

      <Step title="Verify the connection">
        At this point, you should be able to use the Omni MCP server in your Claude Desktop chats.

        In a chat, click the <Icon icon="plus" iconType="solid" /> (plus) icon, then **Connectors**. Your Omni MCP connection should be enabled:

        <img src="https://mintcdn.com/omni-e7402367/XIpn-9Hi2cNutp5u/ai/images/claude-mcp-in-chat.png?fit=max&auto=format&n=XIpn-9Hi2cNutp5u&q=85&s=725773ff48261499c426a664b82c12ed" alt="Claude Desktop chat with the Omni connector enabled" width="1018" height="863" data-path="ai/images/claude-mcp-in-chat.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="API Key">
    API key authentication gives you direct control over key management.

    <Steps>
      <Step title="Create an API key">
        If you don't have an Omni API key, [create one](/api/authentication) before continuing.
      </Step>

      <Step title="Open Claude Desktop settings">
        In Claude Desktop, navigate to **Settings > Developer**.
      </Step>

      <Step title="Edit the config file">
        Click **Edit Config**. This opens (or creates) `claude_desktop_config.json`.
      </Step>

      <Step title="Add the MCP server">
        Add the following to the `mcpServers` key:

        ```json title="claude_desktop_config.json" theme={null}
        {
          "mcpServers": {
            "Omni MCP": {
              "command": "npx",
              "args": ["@omni-co/mcp"],
              "env": {
                "DEBUG": "true",
                "MCP_SERVER_URL": "https://<YOUR_OMNI_INSTANCE>/mcp/https",
                "MCP_API_KEY": "<OMNI_API_KEY>",
                "MCP_MODEL_ID": "<OPTIONAL_OMNI_MODEL_ID>",
                "MCP_TOPIC_NAME": "<OPTIONAL_TOPIC_NAME>",
                "MCP_USER_REQUIRED": "<true/false>",
                "MCP_USER_ID": "<USER_ID>"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Configure the server">
        Replace the placeholder values:

        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL (e.g., `acme.omniapp.co`)
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication)
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific model. Find the model ID in the URL when viewing the model:
          ```txt wrap theme={null}
          https://acme.omniapp.co/models/9d9440e5-8522-4507-b092-1ac26ba26673/ide/model
          ```
        * `<OPTIONAL_TOPIC_NAME>` - **Optional**. Scope the MCP to a specific topic
        * `<true/false>` - **Optional**. Require a User ID to execute queries with that user's permissions (default: false)
        * `<USER_ID>` - **Optional**. Execute queries as this user. Get IDs from the [List Users API](/api/users/list-users)
      </Step>

      <Step title="Restart Claude Desktop">
        Save the file and restart Claude Desktop.
      </Step>

      <Step title="Verify the connection">
        Navigate to **Settings > Developer** and click **Omni MCP**. You should see a `running` badge:

        <img src="https://mintcdn.com/omni-e7402367/t-IfvrVPwJe-flyV/ai/images/mcp-claude-server-status.png?fit=max&auto=format&n=t-IfvrVPwJe-flyV&q=85&s=069f0dc1babf6a82294d4f1d3c91abbf" alt="Claude Desktop MCP Server status showing running badge" width="874" height="412" data-path="ai/images/mcp-claude-server-status.png" />
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

Once the MCP Server is connected, Claude Desktop automatically uses it when you ask questions about your data. You can prompt Claude to use Omni by referring to it by name or description.

1. Enter a prompt in the chat panel, such as `Hey Omni, tell me how many users have been sourced by referrals`.

2. Each time Claude uses an MCP tool, you'll be prompted to approve its usage. Click **Allow once** or **Allow always** to proceed:

   <img src="https://mintcdn.com/omni-e7402367/t-IfvrVPwJe-flyV/ai/images/mcp-claude-allow-prompt.png?fit=max&auto=format&n=t-IfvrVPwJe-flyV&q=85&s=75ac03f0363ac9aab5cb3425a36f208d" alt="Claude Desktop MCP approval prompt" width="503" height="398" data-path="ai/images/mcp-claude-allow-prompt.png" />

3. The MCP Server will pick a model (if not configured) and topic, then run a query to retrieve the data:

   <img src="https://mintcdn.com/omni-e7402367/t-IfvrVPwJe-flyV/ai/images/mcp-claude-chat.png?fit=max&auto=format&n=t-IfvrVPwJe-flyV&q=85&s=72eb30ef6bf6547ff587bef3029f1b2e" alt="Claude Desktop chat with MCP Server running a query" width="1050" height="818" data-path="ai/images/mcp-claude-chat.png" />