Connect Codex

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

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

Prerequisites

You need your Azure Databricks workspace URL and access to the models, MCPs, and skills you want to use. Install the latest version of Codex or the ChatGPT desktop app.

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

Codex in the terminal

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.

ChatGPT desktop

On macOS and Linux, install ug and run this command in an interactive terminal:

ug configure --agents codex

Select your workspace and sign in. If prompted, approve the system configuration update with your device password. ug configures the Unity Gateway connection and OAuth token refresh.

Open or restart the desktop app and start a Codex conversation. Use the model picker to change models. The ug codex command opens the terminal agent; open the desktop app normally after configuration.

On Windows, use the manual model configuration below. You can still use ug mcp add and ug skills add to add tools and skills, then restart the app.

Configure models manually

These settings apply to both the terminal agent and desktop app. 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 or reopen the desktop app. 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

To use system.ai.dbsql, system.ai.sandbox, or system.ai.web_search, an account admin must enable the Unity Gateway beta from the account console Previews page. See Manage account previews.

  1. Open Unity Gateway > MCPs in your workspace. Choose a built-in MCP or register your external MCP server.
  2. Copy the MCP's full name, such as system.ai.github or <catalog>.<schema>.<service>.
  3. 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 Codex with ug codex, or reopen the desktop app, then test a tool.

Configure MCPs manually

Use a public Azure Databricks OAuth app to sign in and refresh credentials. These settings apply to the terminal agent and desktop app.

Set up an OAuth app

  1. 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"

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

  3. Register the MCP in Codex, replacing the placeholders:

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

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

  5. Sign in, then reopen Codex:

    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 and token:

[mcp_servers.dbsql]
url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"
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

  1. In Codex, enter /mcp and check that the server is connected.
  2. 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.
  3. 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.
  4. 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 Codex or the desktop app. 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

  • The desktop app still asks for OpenAI sign-in: On macOS or Linux, rerun ug configure --agents codex interactively and complete the system configuration update. The CLI profile alone does not configure the desktop app. For manual setup, check that model_provider is at the top level and requires_openai_auth = false is in the provider table. Do not add that flag to a provider that uses an auth table for OAuth token refresh.

  • 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

  • Last updated on