> ## 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-code",
  "feedback": "Description of the issue"
}
```

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

</AgentInstructions>

# Using the MCP Server in Claude Code

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

Claude Code is the command line version of Anthropic's AI assistant, Claude. Once successfully connected to Omni, you can interact with your Omni data right in your Claude Code session.

**Looking for the Omni agent skills for Claude Code?** See the [Agent skills documentation](/developers/agent-skills) for a broader set of skills beyond querying.

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

## 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:

* To install Claude Code
* To have the following enabled in Omni:
  * **The MCP Server AI setting**. An Organization Admin can enable this setting by navigating to **Settings > AI > General**.
  * **Personal access tokens (PATs)**. An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#personal-access-tokens-pat).

## Setup

<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. This adds the Omni MCP server to both Claude Desktop and Claude Code.
      </Step>

      <Step title="Start a new Claude Code session">
        Run `claude` to start a new session. The Omni MCP server will be available automatically.
      </Step>

      <Step title="Authorize the connection">
        1. Claude Code will detect the Omni connector and prompt you to authenticate.
        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 Code sessions:

        <img src="https://mintcdn.com/omni-e7402367/6iIWbjntnIlPNzqp/ai/images/claude-code-success.png?fit=max&auto=format&n=6iIWbjntnIlPNzqp&q=85&s=55f2dde2b2c2453be6f4ed69020b273f" alt="Claude Code session with the Omni MCP server connected" width="1140" height="522" data-path="ai/images/claude-code-success.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual CLI Setup">
    You can also add the Omni MCP server manually via the Claude Code CLI.

    <Steps>
      <Step title="Add the Omni MCP server">
        In your terminal, run the following command:

        ```bash theme={null}
        claude mcp add --transport http omni https://callbacks.omniapp.co/callback/mcp
        ```
      </Step>

      <Step title="Start a new Claude session">
        Run `claude` to start a new session.
      </Step>

      <Step title="Authenticate with Omni">
        1. Run `/mcp` to open the MCP servers list:
                   <img src="https://mintcdn.com/omni-e7402367/6iIWbjntnIlPNzqp/ai/images/claude-code-needs-auth.png?fit=max&auto=format&n=6iIWbjntnIlPNzqp&q=85&s=c0e30a5fa756cecee413ff5eb88db027" alt="Claude Code MCP servers list showing Omni needs authentication" width="1022" height="347" data-path="ai/images/claude-code-needs-auth.png" />
        2. Navigate to and select the Omni MCP server:
                   <img src="https://mintcdn.com/omni-e7402367/6iIWbjntnIlPNzqp/ai/images/claude-code-authenticate.png?fit=max&auto=format&n=6iIWbjntnIlPNzqp&q=85&s=5f6eefed189ac4c423690fc678d7a8b5" alt="Claude Code MCP server selection" width="1018" height="366" data-path="ai/images/claude-code-authenticate.png" />
        3. Press **Enter** to select the **Authenticate** option.
                   <img src="https://mintcdn.com/omni-e7402367/6iIWbjntnIlPNzqp/ai/images/claude-code-redirect.png?fit=max&auto=format&n=6iIWbjntnIlPNzqp&q=85&s=509e9cf5e092f100e9026e60f7c53a52" alt="Claude Code authentication redirect prompt" width="1013" height="335" data-path="ai/images/claude-code-redirect.png" />
        4. Your browser will open and redirect you to an Omni authorization page.
        5. 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 Code sessions:

        <img src="https://mintcdn.com/omni-e7402367/6iIWbjntnIlPNzqp/ai/images/claude-code-success.png?fit=max&auto=format&n=6iIWbjntnIlPNzqp&q=85&s=55f2dde2b2c2453be6f4ed69020b273f" alt="Claude Code session with the Omni MCP server connected" width="1140" height="522" data-path="ai/images/claude-code-success.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code Cloud">
    Claude Code Cloud runs agents on your repositories in the cloud. MCP servers are configured by committing a `.mcp.json` file to the root of any repository where you want Omni available.

    <Note>
      You'll need an Omni API key for this setup. See [API authentication](/api/authentication) if you need to create one.
    </Note>

    <Steps>
      <Step title="Create the .mcp.json file">
        In the root of your repository, create a file named `.mcp.json`:

        ```json title=".mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni MCP": {
              "type": "http",
              "url": "https://<YOUR_OMNI_INSTANCE>/mcp/https",
              "headers": {
                "Authorization": "Bearer <OMNI_API_KEY>",
                "X-MCP-Model-ID": "<OPTIONAL_OMNI_MODEL_ID>",
                "X-MCP-Topic-Name": "<OPTIONAL_TOPIC_NAME>",
                "X-MCP-User-Required": "<true/false>",
                "X-MCP-User-ID": "<USER_ID>",
                "X-MCP-Query-All-Views": "<true/false>"
              }
            }
          }
        }
        ```

        Replace the placeholder values:

        * `<YOUR_OMNI_INSTANCE>` - **Required**. Your Omni URL
        * `<OMNI_API_KEY>` - **Required**. Your [Omni API key](/api/authentication)
        * `<OPTIONAL_OMNI_MODEL_ID>` - **Optional**. Scope the MCP to a specific 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)
        * `<true/false>` for `X-MCP-Query-All-Views` - **Optional**. Set to `true` to enable all-views-and-fields mode, allowing the AI to query any view in the model (not just topics). Requires the model's `query_all_views_and_fields` setting to be enabled. Default: `false`.
      </Step>

      <Step title="Commit the file">
        Commit `.mcp.json` to your repository. When you start a new Claude Code Cloud session on that repository, the MCP server will be loaded automatically.

        **To keep credentials out of version control**, reference environment variables using `${VAR}` syntax instead of hardcoding values:

        ```json title=".mcp.json" theme={null}
        {
          "mcpServers": {
            "Omni MCP": {
              "type": "http",
              "url": "https://${OMNI_INSTANCE}/mcp/https",
              "headers": {
                "Authorization": "Bearer ${OMNI_API_KEY}",
                "X-MCP-Model-ID": "${OMNI_MODEL_ID}",
                "X-MCP-Topic-Name": "${OMNI_TOPIC_NAME}",
                "X-MCP-User-Required": "false",
                "X-MCP-Query-All-Views": "${OMNI_QUERY_ALL_VIEWS}"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Add Cloud Environment variables">
        If you used `${VAR}` references in your `.mcp.json`, add the corresponding values to your Cloud Environment variables (e.g., `OMNI_API_KEY=key`). These are injected at runtime and never stored in your repository.
      </Step>

      <Step title="Start a new session">
        Start a new Claude Code Cloud session from [claude.ai/code](https://claude.ai/code) or the Claude desktop app. When prompted, select the GitHub repository where you committed `.mcp.json`. Claude Code Cloud will detect the file and load the Omni MCP server automatically.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tool denial in 'don't ask' mode">
    Claude Code may sometimes return an error similar to:

    ```bash wrap theme={null}
    Permission to use mcp__omni__pickModel has been denied because Claude Code is running in don't ask mode
    ```

    This mode automatically blocks tools that aren't pre-approved rather than prompting you for approval. To resolve this issue, you have a few options:

    * **Restart Claude Code with the tools allowed**:
      ```bash theme={null}
      claude --allowed-tools 'mcp__omni__*'
      ```
    * **Update your permission settings** to allow MCP tools. Add `mcp__omni__*` to your allowed tools in your Claude Code settings or `.claude/settings.json`
    * **Switch out of 'don't ask' mode**, which will ensure you are prompted to approve tool calls
  </Accordion>
</AccordionGroup>