Skip to main content
Last updated on

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.

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

Prerequisites​

You need your 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.

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

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

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.

Toml
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​

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:

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

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

    Bash
    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

  2. Sign in, then reopen Codex:

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

Then test a tool.

Set up a custom 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:

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

    Bash
    codex mcp add databricks-tools \
      --url "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>?o=<workspace-id>" \
      --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:

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

Toml
[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​

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

Bash
ug skills add

Or download a specific published skill:

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

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

Connect the skill registry manually​

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

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 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​

On this page