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

# Using the MCP Server in Codex

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

Codex is OpenAI's agentic coding tool that can connect to external data sources with MCP. Once successfully connected to Omni, you can interact with your Omni data right in your Codex sessions.

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

* [Codex](https://openai.com/index/codex/) installed (CLI or IDE extension)
* 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)**, which are required to use [OAuth to authenticate](/ai/mcp/authentication). An Organization Admin can activate them by going to [**Settings > API Keys > Personal tokens**](/api/authentication#personal-access-tokens-pat).

## Setup

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

<Tabs>
  <Tab title="OAuth (Recommended)">
    OAuth provides streamlined setup without manually managing API keys.

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

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

      <Step title="Start a Codex session">
        Run `codex` to start a new session. Codex will detect the Omni MCP server and initiate the OAuth flow.
      </Step>

      <Step title="Authenticate with Omni">
        1. Your browser will open and 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 Codex sessions.
      </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="Configure the MCP server">
        You can add the server via CLI or by editing the Codex config file directly.

        **Option A: CLI**

        ```bash theme={null}
        codex mcp add omni https://<YOUR_OMNI_INSTANCE>/mcp/https
        ```

        **Option B: Config file**

        Edit `~/.codex/config.toml` (user-level) or `.codex/config.toml` (project-scoped) and add:

        ```toml config.toml theme={null}
        [mcp_servers.omni]
        url = "https://<YOUR_OMNI_INSTANCE>/mcp/https"

        [mcp_servers.omni.http_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 = "<OPTIONAL_OMNI_USER_ID>"
        X-MCP-Query-All-Views = "<true/false>"
        ```
      </Step>

      <Step title="Replace 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)
        * `<OPTIONAL_OMNI_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 allow the AI to query any view in the model instead of only topics. Requires the model's [`query_all_views_and_fields`](/modeling/models/ai-settings#param-query-all-views-and-fields) setting to be enabled. Defaults to `false`.
      </Step>

      <Step title="Verify the connection">
        Start a new Codex session and confirm the Omni MCP server is available.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Using the MCP

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

<Steps>
  <Step>
    Start a Codex session and enter a prompt, such as `Hey Omni, tell me how many users signed up last month`.
  </Step>

  <Step>
    Codex may prompt you to approve MCP tool usage. Approve the tool call to proceed.
  </Step>

  <Step>
    The MCP Server will pick a model (if not configured) and topic, then run a query to retrieve the data.
  </Step>
</Steps>