Connect Codex

Use Codex in your terminal with models, MCP tools, and skills through Unity Gateway. Use the Unity Gateway CLI (ug) to configure access, or configure the connection manually.

Use Codex CLI with supported open-source models through Unity Gateway to help reduce coding agent costs.

To connect tools to an existing Codex setup, go to Add MCP tools.

Prerequisites

You need your Azure Databricks workspace URL, access to the models, MCPs, and skills you want to use, and the latest Codex CLI.

If your admin has already configured your device, follow your organization's launch instructions.

Use the Unity Gateway CLI (recommended)

Install ug, then run this command from your project directory:

ug codex

Follow the prompts to select your workspace and sign in. ug configures the connection and opens Codex in your terminal. Start working with the same prompts and commands you already use. To change models, enter /model.

Continue to Add MCP tools or Add skills to give Codex access to data and shared instructions.

Bring your own ChatGPT subscription

To run Codex on your own ChatGPT Go, Plus, Pro, or Enterprise subscription through Unity Gateway, ask your admin for a ChatGPT subscription model provider service. See ChatGPT subscription support for requirements, admin setup, how it works, and limitations.

Pass the model provider service's fully qualified name (<catalog>.<schema>.<name>) to --provider and the workspace URL to --workspace:

ug codex --provider main.default.chatgpt_subscription --workspace https://<workspace>.databricks.com

If Codex isn't signed in with ChatGPT, ug runs codex login to open the browser sign-in. An API key sign-in doesn't count. ug configures Codex to send the Databricks-Model-Provider-Service header and points Codex at a local refresh proxy rather than directly at the Unity Gateway endpoint. The proxy forwards each request to https://<workspace-url>/ai-gateway/codex/v1 and adds the X-Databricks-AI-Gateway-Token header. Because the service stores no credential, the proxy passes your ChatGPT sign-in through without storing it.

If you run into issues, sign out with codex logout, then rerun the command to sign in again.

Note

--provider for a ChatGPT subscription model provider service is only supported with ug codex. Smart Routing isn't supported with a ChatGPT subscription model provider service.

Configure a ChatGPT subscription manually

Use the manual setup only if you cannot use ug.

Get a Azure Databricks token. The X-Databricks-AI-Gateway-Token header carries a Azure Databricks token that authenticates the request to Unity Gateway. Unity Gateway attributes access control and usage logs to the identity tied to this token, so use a token that belongs to the querying user. Select one of the following:
- OAuth user-to-machine (U2M) with the Databricks CLI (recommended). Log in once with the CLI, then mint a short-lived OAuth token:
```
databricks auth login --host https://<workspace-url>
databricks auth token --host https://<workspace-url> | jq -r .access_token
```
  See Authorize user access to Azure Databricks with OAuth and Authentication for the Databricks CLI. A U2M OAuth token expires in about 1 hour, so for interactive use you must replace it in your configuration when it expires. To automate token refresh, use ug, which runs a local proxy that refreshes the OAuth token for you on every request.
- Personal access token (PAT), as a backup. If you cannot use OAuth, create a PAT and use it as <databricks-token>. A PAT does not expire on the 1-hour OAuth cadence, but it is a long-lived credential tied to your identity. See Authenticate with Azure Databricks personal access tokens (legacy).
Close Codex, then open or create ~/.codex/config.toml. On Windows, use %USERPROFILE%\.codex\config.toml. Merge the following settings into the file. Keep model_provider at the top level, before any table headers, and preserve unrelated settings.
```
model_provider = "databricks"

[model_providers.databricks]
name = "Databricks"
base_url = "https://<workspace-url>/ai-gateway/codex/v1"
wire_api = "responses"
requires_openai_auth = true
http_headers = { "X-Databricks-AI-Gateway-Token" = "Bearer <databricks-token>", "Databricks-Model-Provider-Service" = "<catalog>.<schema>.<name>" }
```
- Replace <workspace-url> with your workspace URL.
- Replace <databricks-token> with the Azure Databricks token from the previous step.
- Replace <catalog>.<schema>.<name> with the fully qualified name of your model provider service.
requires_openai_auth = true makes Codex send its own ChatGPT sign-in. Don't add an auth table to this provider. Keep the file private, because it stores your Azure Databricks token.
Start Codex:
```
codex
```
If you are not already signed in, Codex prompts you to authenticate. Select Sign in with ChatGPT and sign in with your ChatGPT account. An API key sign-in doesn't work with a ChatGPT subscription model provider service. If you run into issues, sign out with codex logout and sign in again.

Your Codex requests now route through Unity Gateway. Requests are billed against your ChatGPT subscription, and you get centralized access, routing, and usage governance.

Run on Azure Databricks compute

To run Codex on serverless compute or a dedicated cluster without installing ug, connect with the SSH tunnel and run codex. The agent is preconfigured for Unity Gateway. See Run coding agents in an SSH session.

Configure models manually

Close Codex, then open or create ~/.codex/config.toml. On Windows, use %USERPROFILE%\.codex\config.toml.

Merge the following settings into the file. Keep model and model_provider at the top level, before any table headers, and preserve unrelated settings.

model = "<catalog>.<schema>.<model-name>"
model_provider = "databricks"

[model_providers.databricks]
name = "Databricks"
base_url = "https://<workspace-hostname>/ai-gateway/codex/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
http_headers = { Authorization = "Bearer <databricks-pat>" }

Replace the model placeholder with its full Unity Catalog name, <workspace-hostname> with your workspace hostname, and <databricks-pat> with your personal access token. This example stores the token locally; keep the file private and use your own token.

Run codex from your project directory. If your device has managed provider settings, ask your admin to update them; those settings take precedence over this user configuration.

See OpenAI's configuration reference for field details.

Add MCP tools

system.ai.dbsql, system.ai.sandbox, and system.ai.web_search are in Beta. To use them, an account admin must enable the Enhanced Unity Gateway preview from the account console Previews page. Unity Gateway itself is generally available. See Manage account previews.

Open Unity Gateway > MCPs in your workspace. Choose a built-in MCP or register your external MCP server.
Copy the MCP's full name, such as system.ai.github or <catalog>.<schema>.<service>.
Confirm that you have access to the MCP.

Use the Unity Gateway CLI

Install ug, then add the MCP to Codex:

ug mcp add --agents codex --names <catalog>.<schema>.<service>

Replace the placeholder with the name you copied. For example, use --names system.ai.github for GitHub. To choose services interactively, omit --names.

On first setup, follow the prompts to select your workspace, sign in, and choose a model. ug configures both model and MCP access and refreshes credentials. For MCP access with your own OAuth app, use the manual setup below.

Restart the Codex CLI with ug codex, then test a tool.

Configure MCPs manually

Use a public Azure Databricks OAuth app to sign in and refresh credentials.

To use the default Codex client ID, which doesn't need an account admin to create an OAuth app:

codex mcp add databricks-tools \
  --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>" \
  --oauth-client-id https://chatgpt.com/oauth/codex/client.json

codex mcp login databricks-tools --scopes ai-gateway,offline_access

Then test a tool.

Set up a custom OAuth app

Close Codex. In ~/.codex/config.toml, add these settings at the top level, before any table headers. They give the local OAuth callback a fixed port:
```
mcp_oauth_callback_port = 8080
mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"
```
Have an account admin open Settings > App connections > Add connection in the account console. Use a name such as codex-mcp, clear Generate a client secret, set the redirect URL to http://127.0.0.1:8080/callback, and select the ai-gateway scope. Save and copy the Client ID. See Create an OAuth app.

codex mcp add databricks-tools \
  --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>" \
  --oauth-client-id <client-id>

Check the callback URL printed by Codex. It can include a server-specific suffix. Have the admin add that exact URL to the OAuth app's redirect URLs before signing in. Repeat this check when adding another server.

codex mcp login databricks-tools --scopes ai-gateway,offline_access

For callback settings, see OpenAI's MCP authentication instructions. Then test a tool.

Use a personal access token for local testing

Add the following to ~/.codex/config.toml, replacing the hostname, workspace ID, and token:

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql?o=<workspace-id>"
http_headers = { Authorization = "Bearer <databricks-pat>" }

For another MCP, use a unique name under mcp_servers and replace system.ai.dbsql with its full name. Keep the file private, then restart Codex and test a tool.

Test an MCP tool

In Codex, enter /mcp and check that the server is connected.
Ask Codex to list that server's tools, then request a read operation. For GitHub, ask it to find an issue in a repository you can access. For a custom server, use a tool and inputs you tested during registration.
If a tool call prompts you to sign in, open the login link returned by the MCP, complete provider consent, then retry the call. This sign-in gives the MCP access to your external account.
Check that Codex makes a tool call and returns its result. A text answer alone doesn't verify the connection.

To use Azure Databricks data, connect system.ai.genie_one_mcp for business questions or system.ai.dbsql for SQL. For example, ask the SQL MCP to run SELECT 1 AS result.

For permissions, policies, and usage, see Govern an MCP.

Add skills

Use the Unity Gateway CLI

Run the interactive picker:

ug skills add

Or download a specific published skill:

ug skills add --names <catalog>.<schema>.<skill-name>

Restart the Codex CLI. Downloaded skills are available locally in ~/.agents/skills/. Re-run the download to get an updated version.

To expose a schema's skills through MCP instead, run:

ug skills add --location "<catalog>.<schema>" --via mcp

Connect the skill registry manually

Add the following to ~/.codex/config.toml:

[mcp_servers.databricks-skill-registry]
url = "https://<workspace-hostname>/ai-gateway/skills/"
http_headers = { Authorization = "Bearer <databricks-pat>" }

Replace the hostname and token. Keep the trailing slash in the URL. Restart Codex and ask it to use a published skill, such as Use <catalog>.<schema>.<skill-name> to review this query.

The registry loads skill instructions through MCP. To install skill files you already have, place the complete skill folder, including SKILL.md and bundled files, in ~/.agents/skills/.

Unity Gateway skills are in Beta. See Govern skills for enablement and permissions.

Troubleshooting

Requests fail with a WebSocket error: Set supports_websockets = false in the active Azure Databricks provider table. If your admin manages that configuration, ask them to update it. Restart the app afterward.
A model is missing: Check your model permissions. Set model to its full Unity Catalog name in the active configuration and start a new conversation.
An MCP or skill connection fails: Check the URL, permissions, and connector error. For manual connections, also check token expiration. For ug setup problems, run ug doctor. A downloaded skill can remain available even if the registry connection fails.
Workspace sign-in works, but a tool asks you to log in: Open the login link returned by the MCP, sign in to the external provider, then retry the call. Workspace and provider sign-in are separate steps.
OAuth reports a redirect mismatch or the connection times out: Match the OAuth app's redirect URL to the exact URL Codex reports, including any suffix, and check network access. OAuth app changes can take up to 30 minutes to take effect.

Next steps

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Τελευταία ενημέρωση στις 2026-11-11

Connect Codex

Prerequisites

Use the Unity Gateway CLI (recommended)

Bring your own ChatGPT subscription

Configure a ChatGPT subscription manually

Run on Azure Databricks compute

Configure models manually

Add MCP tools

Use the Unity Gateway CLI

Configure MCPs manually

Test an MCP tool

Add skills

Use the Unity Gateway CLI

Connect the skill registry manually

Troubleshooting

Next steps

Σχόλια

Πρόσθετοι πόροι