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.
- Codex installed (CLI or IDE extension)
- To have the following enabled in Omni:
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 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: CLIcodex mcp add omni https://<YOUR_OMNI_INSTANCE>/mcp/https
~/.codex/config.toml (user-level) or .codex/config.toml (project-scoped) and add:[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>"
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
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.
