メインコンテンツまでスキップ
に最終更新

Codexを接続

Unity Gatewayを通じて、モデル、MCPツール、スキルを使用してターミナルでCodexを使用します。Unity Gateway CLI（ug）を使用してアクセスを設定するか、接続を手動で設定します。

既存のCodexセットアップにツールを接続するには、MCPツールの追加に移動します。

前提条件​

DatabricksワークスペースURL、使用するモデル、MCP、およびスキルへのアクセス権、そして最新の Codex CLI が必要です。

すでに管理者がデバイスを構成している場合は、組織の起動手順に従ってください。

Unity Gateway CLIを使用する（推奨）​

ugをインストールし、プロジェクト ディレクトリから次のコマンドを実行します。

Bash
ug codex

プロンプトに従ってワークスペースを選択し、サインインします。ug により接続が構成され、ターミナルで Codex が起動します。すでに使用している同じプロンプトとコマンドを使用して作業を起動します。モデルを変更するには、/model を入力します。

MCPツールの追加またはスキルの追加に進み、Codexにデータおよび共有インストラクションへのアクセス権を付与します。

モデルを手動で構成する​

Codex を閉じてから、~/.codex/config.toml を開くか作成します。Windows では、%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>" }

モデルのプレースホルダーを完全な Unity Catalog 名に置き換え、<workspace-hostname> にワークスペースのホスト名を、<databricks-pat> に個人用アクセストークンを指定します。この例ではトークンをローカルに保存します。ファイルを非公開にし、ご自身のトークンを使用してください。

プロジェクト・ディレクトリからラン codex を実行してください。デバイスに管理プロバイダーの設定がある場合は、管理者に更新を依頼してください。これらの設定は、このユーザー設定よりも優先されます。

フィールドの詳細については、OpenAIの設定リファレンスを参照してください。

MCPツールを追加​

system.ai.dbsql、system.ai.sandbox、または system.ai.web_search を使用するには、アカウント管理者がアカウント コンソールの Previews ページから Unity Gateway ベータ版を有効にする必要があります。アカウントのプレビューの管理を参照してください。

  1. ワークスペースで Unity Gateway > MCPs を開きます。組み込みMCPを選択するか、外部MCPサーバーを登録するかしてください。
  2. system.ai.githubや<catalog>.<schema>.<service>など、MCPのフルネームをコピーします。
  3. MCP へのアクセス権があることを確認します。

Unity Gateway CLIを使用する​

ugをインストールし、CodexにMCPを追加します:

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

プレースホルダーをコピーした名前に置き換えます。たとえば、GitHubには--names system.ai.githubを使用します。サービスをインタラクティブに選択するには、--namesを省略します。

初期設定で、プロンプトに従ってワークスペースを選択し、サインインして、モデルを選択します。ug はモデルと MCP の両方のアクセスを設定し、資格情報を更新します。独自の OAuth アプリで MCP にアクセスするには、以下の手動セットアップを使用します。

ug codex でCodex CLIを再起動し、ツールをテストします。

Configure MCPs manually​

パブリックDatabricks OAuthアプリを使用してサインインし、認証情報を更新します。

アカウント管理者がOAuthアプリを作成する必要がないdefault CodexクライアントIDを使用するには：

  1. CodexでMCPを登録し、プレースホルダーを置き換えます。

    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. サインインして、Codexを再度開きます：

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

次に、ツールをテストします。

カスタムOAuthアプリのセットアップ

  1. Codexを終了します。~/.codex/config.toml で、テーブルヘッダーの前のトップレベルにこれらの設定を追加します。これにより、ローカルの OAuth コールバックに固定ポートが付与されます。

    Toml
    mcp_oauth_callback_port = 8080
    mcp_oauth_callback_url = "http://127.0.0.1:8080/callback"

  2. アカウント管理者に依頼して、 アカウントコンソール で Settings > App connections > Add connection を開いてもらいます。codex-mcp などの名前を使用し、 [Generate a client secret] の選択を解除し、リダイレクトURLを http://127.0.0.1:8080/callback に設定し、ai-gateway スコープを選択します。 Client ID を保存してコピーします。「Create an OAuth app」を参照してください。

  3. CodexでMCPを登録し、プレースホルダーを置き換えます。

    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. Codexによって出力されたコールバックURLを確認します。サーバー固有のサフィックスを含めることができます。サインインする前に、管理者にその正確なURLをOAuthアプリのリダイレクトURLに追加してもらいます。別のサーバーを追加するときにこのチェックを繰り返します。

  5. サインインして、Codexを再度開きます：

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

コールバック設定については、OpenAIのMCP認証手順を参照してください。次に、ツールをテストします。

ローカルテストには個人用アクセストークンを使用します

~/.codex/config.tomlに以下を追加し、ホスト名、ワークスペースID、トークンを置き換えます。

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

別のMCPの場合は、mcp_serversの下に一意の名前を使用し、system.ai.dbsqlをその完全な名前に置き換えます。ファイルを非公開にしてから、Codexを再起動し、ツールをテストします。

MCP ツールをテストする​

  1. Codex で /mcp を入力し、サーバーが接続されていることを確認します。
  2. Codex にそのサーバーのツールの一覧表示を依頼し、読み取り操作をリクエストします。GitHub の場合、アクセス可能なリポジトリ内の Issue を探すように依頼します。カスタムサーバーの場合は、登録時にテストしたツールと入力を使用します。
  3. ツール呼び出しによってサインインを求められた場合は、MCP が返したログイン Link を開き、プロバイダーの同意を完了してから、呼び出しを再試行してください。このサインインにより、MCP が外部アカウントにアクセスできるようになります。
  4. Codexがツールを呼び出し、その結果を返すことを確認します。テキスト回答だけでは接続を検証できません。

Databricks のデータを使用するには、ビジネス上の質問には system.ai.genie_one_mcp、SQL には system.ai.dbsql に接続します。たとえば、SQL MCP に SELECT 1 AS result をランするよう依頼します。

権限、ポリシー、および使用量については、MCPのガバナンスをご覧ください。

スキルを追加する​

Unity Gateway CLIを使用する​

インタラクティブピッカーを実行します：

Bash
ug skills add

または、特定の公開済みスキルをdownloadします。

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

Codex CLIを再起動します。downloadされたスキルは、ローカルの~/.agents/skills/で利用できます。downloadを再実行して更新バージョンを取得します。

代わりにMCPを介してスキーマのスキルを公開するには、次を実行します。

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

スキル レジストリを手動で接続する​

~/.codex/config.tomlに以下を追加します：

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

ホスト名とトークンを置き換えます。URLの末尾のスラッシュを残します。Codexを再起動し、次のような公開されたスキルを使用するように求めます。 Use <catalog>.<schema>.<skill-name> to review this query.

The registry loads skill instructions through MCP.すでに所有しているスキルファイルをインストールするには、SKILL.mdやバンドルされたファイルを含む完全なスキルフォルダを~/.agents/skills/に配置します。

Unity Gatewayのスキルはベータ版です。有効化とアクセス許可については、スキルのガバナンスを参照してください。

トラブルシューティング​

  • 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 起動 a new conversation.

  • MCPまたはスキル接続が失敗した場合： URL、権限、コネクタのエラーを確認してください。手動接続の場合は、トークンの有効期限も確認してください。ugのセットアップ問題については、ug doctorを実行してください。ダウンロードしたスキルは、レジストリ接続が失敗した場合でも利用可能な状態を維持できます。

  • ワークスペースへのサインインは機能しますが、ツールからログインを求められます: MCPから返されたログインリンクを開き、外部プロバイダーにサインインしてから、呼び出しを再試行します。ワークスペースとプロバイダーのサインインは別々のステップです。

  • OAuth がリダイレクトの不一致を報告するか、接続がタイムアウトする場合: OAuth アプリのリダイレクト URL を、サフィックスを含めて Codex が報告する正確な URL に一致させ、ネットワーク アクセスを確認します。OAuth アプリの変更が反映されるまでに最大 30 分かかる場合があります。

Next steps​

このページの見出し