Using the MCP Server in Codex

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

Every person who wants to use the MCP Server must complete the setup.

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

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 AI Hub > MCP.
- Personal access tokens (PATs), which are required to use OAuth to authenticate. An Organization Admin can activate them by going to Settings > API Keys > Personal tokens.

Setup

Choose your authentication method. See the MCP authentication guide if you need help selecting a method.

OAuth (Recommended)
API Key

OAuth provides streamlined setup without manually managing API keys.

Add the Omni MCP server

In your terminal, run the following command:

codex mcp add omni --url https://callbacks.omniapp.co/callback/mcp

Start a Codex session

Run codex to start a new session. Codex will detect the Omni MCP server and initiate the OAuth flow.

Authenticate with Omni

Your browser will open and redirect you to an Omni authorization page.
Review the requested permissions and click Authorize.

Omni will automatically create a Personal access token and link it to your Omni user account.

Verify the connection

At this point, you should be able to use the Omni MCP server in your Codex sessions.

API key authentication gives you direct control over key management.

Create an API key

If you don’t have an Omni API key, create one before continuing.

Configure the MCP server

You can add the server via CLI or by editing the Codex config file directly.Option A: CLI

codex mcp add omni https://<YOUR_OMNI_INSTANCE>/mcp/https

Option B: Config fileEdit ~/.codex/config.toml (user-level) or .codex/config.toml (project-scoped) and add:

config.toml

[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>"

Replace placeholder values

<YOUR_OMNI_INSTANCE> - Required. Your Omni URL (e.g., acme.omniapp.co)
<OMNI_API_KEY> - Required. Your Omni API key
<OPTIONAL_OMNI_MODEL_ID> - Optional. Scope the MCP to a specific model. Find the model ID in the URL when viewing the model:
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
<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 setting to be enabled. Defaults to false.

Verify the connection

Start a new Codex session and confirm the Omni MCP server is available.

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.

Start a Codex session and enter a prompt, such as Hey Omni, tell me how many users signed up last month.

Codex may prompt you to approve MCP tool usage. Approve the tool call to proceed.

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

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

Using the MCP Server in Codex

Requirements

Setup

Using the MCP

​Requirements

​Setup

​Using the MCP

Requirements

Setup

Using the MCP