Supabase MCPとCodexの接続手順｜設定・確認のポイント

Supabase MCPとCodexを今確認する理由

Supabase MCPとCodexの組み合わせをいま整理する理由は、単にデータベースを自然文で操作できるからではありません。接続先、見える機能、変更できる範囲が、使うMCPクライアントとSupabase側の選択によって変わるためです。接続に成功したように見えても、別のプロジェクトを参照していたり、必要以上の機能が有効だったりすれば、確認のしやすさと安全性を損ないます。最初に「何を見せるか」「何をさせないか」「どの結果を人が確認するか」を決めることが、実用上の出発点になります。

2026年9月17日に確認したSupabaseのAI Tools公式ページには、Codex Plugin + MCPがAIコーディングエージェントの選択肢として掲載されています。従来のようにCodexへデータベースの説明を長く貼り付ける方法だけでなく、接続中のプロジェクトを参照する入口を比較できる状態になっています。ただし、掲載されていることは、すべてのプラン、地域、クライアント版で同じ表示になることを意味しません。自分の画面と使用版を確認する必要があります。

さらに、OpenAIのCodex CLI公式リファレンスでは、codex mcp add によるURL登録、codex mcp list による一覧表示、codex mcp get による個別設定の確認が案内されています。OpenAIのCodex公式リリース一覧では、2026年9月16日公開の 0.155.0-alpha.9 を含む先行版が確認できますが、今回のリリース一覧からSupabase固有の機能追加までは読み取りません。版の公開事実とMCP接続の仕様を混同せず、公式リファレンスを基準にします。

2026年9月17日に確認できる情報の範囲

当日に確定できるのは、Supabase公式ページにCodex Plugin + MCPの入口があること、Supabase MCPの接続資料がプロジェクト指定や機能グループの選択を案内していること、OpenAI Codex CLIの資料がURL形式のMCPサーバー登録を案内していることです。これらは公式ページに書かれた事実として扱います。一方、画面の展開時期、アカウントごとの表示、接続後の応答速度は環境によって変わるため、記事だけで保証しません。

OpenAIの最新先行版が公開されたからといって、Supabase MCPがその版で新しく使えるようになったと断定するのも避けます。リリースページにSupabaseの記載がない場合は、版番号とMCP設定の確認を分けます。読者が自分の環境で再確認できるよう、公式URL、確認コマンド、最初に尋ねる質問を同じ流れへ置くのが本記事の範囲です。

既存のSupabase開発記事と接続記事の違い

SupabaseとCodexを使ってテーブル設計やTypeScriptを進める記事では、Codexに要件やファイルを渡し、生成されたコードを確認する流れが中心になります。Supabase MCPの記事で先に扱うのは、コード生成の方法ではなく、CodexからSupabaseへ情報を取りに行く経路です。接続できていない状態でスキーマを推測させるのか、接続済みの情報を参照させるのかで、最初に渡す指示も確認方法も変わります。

本記事は、既存のSupabase開発、一般的なMCP、Codexの設定解説を置き換えません。プロジェクトを限定し、最初に読み取り結果を確認し、その後に必要な作業だけを広げるための接続ガイドです。データベース設計の正しさや本番反映の判断は、MCPが接続できた後も人が担当します。

Supabase MCPとCodexの役割を分ける

MCPを初めて使うと、「CodexにSupabaseの機能が内蔵された」と考えやすくなります。実際には、CodexとSupabaseの間に、決められた形式で情報を受け渡すサーバーが置かれます。Codexは会話の指示と作業の文脈を持ち、MCPサーバーはSupabaseのプロジェクトに対するツールを提示し、Supabase側が実際のデータや設定を返します。役割を分けておけば、問題が起きたときにCodexの指示、MCP登録、Supabaseの権限、プロジェクト状態を別々に調べられます。

Supabase公式資料では、MCPサーバーを通じてテーブル一覧、マイグレーション一覧、SQL、ログ、TypeScript型生成などを扱えると説明されています。ただし、ツールの一覧に表示されることと、すべての操作を実行してよいことは別です。読み取り用の確認と、変更を伴う操作を同じ依頼に混ぜないことが、最初の切り分けを簡単にします。出典: Supabase MCP Server公式ドキュメント。

Codex側は接続先と確認方法を持つ

Codex CLI側では、MCPサーバーに付ける名前、接続URL、必要ならローカル起動コマンド、接続後の確認方法を管理します。現行の公式リファレンスは、codex mcp add <name> --url <value> の形でストリーム可能なHTTPサーバーを登録できること、list と get で登録内容を確認できることを説明しています。ここで表示される設定は、Supabaseのプロジェクト内のテーブルを保証するものではありません。登録名とURLを先に読み返し、対象プロジェクトが意図どおりかを確認します。

設定ファイルを直接編集する方法もありますが、最初は公式CLIの登録コマンドを使うほうが入力の違いを減らせます。直接編集した場合は、キーの綴りやURLの引用符、既存のMCPサーバー設定との重複を確認します。Codexの設定画面や診断表示に出る mcp_servers の内容と、実際に参照したいSupabaseのURLが一致していることが重要です。出典: OpenAI Codex CLIの開発者コマンド。

Supabase側はプロジェクトと機能を持つ

Supabase側のMCPサーバーは、どのプロジェクトへ接続するか、どの機能グループを有効にするか、読み取りに限定するかを選べる形で案内されています。公式ドキュメントには project_ref、read_only=true、features の例があります。プロジェクト指定を省くと対象範囲が広くなる可能性があるため、最初の接続ではプロジェクトを明示し、必要な機能だけを選ぶのが基本です。

たとえば、最初は docs、database、debugging、development のような参照中心の機能群に絞り、Edge Functionsやブランチ操作が必要になった段階で追加の影響を確認します。名前の似たプロジェクトを複数持っている場合は、プロジェクト名だけでなく参照IDも記録します。Codexへ「本番」「開発」と伝えるだけでは接続先の判定にならないため、URLと画面上のプロジェクト名を照合します。

SupabaseのデータとCodexの回答を同一視しない

MCP経由でテーブル一覧が返っても、その結果が要件を満たすとは限りません。Codexは返された構造を説明したり、変更案を作ったりできますが、業務上の意味、アクセス方針、削除や更新の影響を決める担当者ではありません。接続後の回答には、参照したプロジェクト、使ったツール、取得時点、未確認の項目を書かせると、回答を事実と提案に分けやすくなります。

特に本番データでは、一覧取得の結果に個人情報や業務情報が含まれることがあります。必要な列や行を限定し、全件を会話へ持ち込まないことが大切です。最初の質問はスキーマや件数の確認にとどめ、値の取得、更新、削除は目的と範囲を別に確認してから進めます。

接続前に決める三つの境界

接続手順を始める前に、どのプロジェクトを見せるか、どの種類のツールを見せるか、変更を許すかの三点を決めます。これを後回しにすると、接続自体は成功しても、Codexが返した結果を評価できません。Supabase公式のMCP資料は、プロジェクト指定、読み取り専用、機能グループという設定を用意しているため、まずはこれらを小さく選ぶのが分かりやすい進め方です。出典: Supabase MCP Server公式ドキュメント。

プロジェクトを一つに絞る

SupabaseのMCP URLは、接続先を限定するための情報を含められます。最初の検証では、複数プロジェクトへ横断的に接続する設定を避け、開発用の一つを選びます。プロジェクト名が似ている場合は、Supabaseの画面で参照IDを確認し、URLの project_ref と照合します。作業開始時にCodexへ「接続先のプロジェクト名と参照IDを説明してから進める」と頼むと、期待する場所に接続できているかを会話の冒頭で確認できます。

読み取りから始める

最初の接続でテーブルを作ったり、既存データを書き換えたりする必要はありません。read_only=true を付けたURLを使い、テーブル一覧、マイグレーション一覧、ログの絞り込みなど、結果を見て判断できる質問から始めます。読み取り結果が想定と違う場合に、書き込みまで許していると原因と影響が同時に広がります。接続が正しいと分かってから、別の確認を経て必要な変更を検討します。

機能グループを必要な分だけ選ぶ

Supabase公式ドキュメントでは、MCPサーバーの機能を features パラメーターで限定できます。データベースの構造を見るだけなら、開発、デバッグ、ドキュメントなどの範囲で十分なことがあります。Edge Functionsの一覧やブランチの操作が必要でない限り、最初からすべてを有効にしないほうが、Codexが選ぶツールと確認対象を把握しやすくなります。機能を追加したときは、追加前後の一覧を記録します。

Codex CLIからSupabase MCPを登録する手順

ここでは、Supabase公式が示すリモートMCP URLを、Codex CLIの公式コマンドで登録する流れを説明します。画面の名称や提供状況は更新されることがあるため、URLは記事から手入力で作り込まず、Supabaseの公式設定画面で選んだプロジェクトと機能を反映させてください。以下の例は、開発用プロジェクトを読み取り中心で確認するための形です。出典: Supabase MCP Server公式ドキュメント、OpenAI Codex CLI公式リファレンス。

Step 1: Supabase公式画面で接続URLを作る

SupabaseのMCPページを開き、ホスト型のサーバーを選びます。対象プロジェクトを一つ指定し、最初は読み取り専用を選び、必要な機能グループだけを残します。表示されたURLには参照IDや機能の指定が含まれるため、コピーする前にプロジェクト名を確認します。URLを一般的な例へ置き換えると対象が変わる可能性があるので、画面から得た値を基準にします。

https://mcp.supabase.com/mcp?project_ref=<PROJECT_REF>&read_only=true&features=docs%2Cdatabase%2Cdebugging%2Cdevelopment

上の <PROJECT_REF> は実際の参照IDへ置き換えます。記事の例をそのまま実行するのではなく、自分のSupabase公式画面で生成されたURLと比較してください。プロジェクト指定を省いたURLや機能を増やしたURLを使う場合は、対象範囲がどう変わるかを先に確認します。

Step 2: Codex CLIへサーバー名とURLを登録する

Codex CLIのMCP登録は、サーバー名のあとにURLを渡します。登録名は後で一覧や個別確認に使うため、supabase のように一目で分かる名前にします。PowerShellでもBashでも、URL全体を引用符で囲んで & が別の記号として扱われないようにします。

codex mcp add supabase --url "https://mcp.supabase.com/mcp?project_ref=<PROJECT_REF>&read_only=true&features=docs%2Cdatabase%2Cdebugging%2Cdevelopment"

OpenAIの公式リファレンスでは、codex mcp add がURL方式とローカルコマンド方式の両方を扱うと説明されています。Supabaseのホスト型サーバーにはURL方式を使います。登録コマンドが未対応と表示された場合は、使用しているCodex CLIの版、ヘルプに出るサブコマンド、公式リファレンスの対応状況を照合し、設定ファイルを直接書き換える前に原因を切り分けます。

Step 3: 登録内容を一覧と個別表示で確認する

登録直後は、接続できたと思い込まず、まず定義を表示します。次のコマンドでサーバー名が一覧に現れるか、個別表示のURLが意図したプロジェクトと機能を指しているかを確認します。

codex mcp list
codex mcp get supabase

ここで確認するのは、表示された名前、URLのホスト、project_ref、read_only、features の有無です。listに名前が出ても、Supabase側の許可が完了したことや、目的のテーブルが見えることまでは意味しません。定義の確認と実際のツール呼び出しを分けて記録します。JSON形式が必要な場合は、公式リファレンスにある --json の説明も参照してください。

Step 4: 参照だけの質問で初回接続を確認する

最初の質問は、データの変更を含まない短いものにします。接続先、表示できるツール、テーブル名を順に確認させ、取得できなかった場合は理由を説明させます。たとえば次のように、更新や移行を行わない条件を明記します。

Supabase MCPの接続確認として、現在のプロジェクト名と参照IDを最初に説明してください。
次に参照できるテーブル名だけを列挙してください。
データの更新、削除、マイグレーションの適用は行わず、使ったMCPツールと未確認の項目を最後に書いてください。

期待するプロジェクト名が返らない場合は、質問の表現を変えて繰り返す前にURLの参照IDを見直します。参照結果が返った場合も、一覧が最新であること、全データを取得したこと、業務上の意味が正しいことを一度に断定しません。

Step 5: 変更が必要になったら別の確認を置く

テーブルの作成、SQLの適用、Edge Functionsの公開など、状態を変える操作が必要になったら、読み取り確認と同じ依頼へ混ぜません。まずCodexに変更案、対象、影響、戻し方、確認するテストを説明させます。その案を人が確認し、開発用の対象で結果を見てから、必要な範囲だけ接続設定や機能グループを広げます。MCPが変更を呼び出せるとしても、実行してよいという判断まで自動で委ねられるわけではありません。

つながったかを確認する方法

接続確認は「登録名が一覧に出たか」だけで終えないことが重要です。MCPサーバーの定義が正しいか、許可画面が完了しているか、Codexが実際にツールを見つけられるか、返ったデータが対象プロジェクトのものかを段階に分けます。各段階で結果を残せば、次に同じ環境を確認する人が、登録の問題とSupabase側の問題を分けて調べられます。

登録定義を確認する

codex mcp list と codex mcp get supabase を実行し、名前とURLを見ます。URLのホストが mcp.supabase.com になっているか、参照IDが開発用プロジェクトと一致するか、読み取り指定と機能指定が残っているかを確認します。設定ファイルを複数の場所で管理している場合は、どの設定層が有効なのかも見直します。登録名が別の定義を指していないか、似た名前のサーバーを二重登録していないかも確認します。

Supabase側の許可と表示を確認する

リモートサーバーへ初めて接続すると、Supabase側のアカウントと対象プロジェクトを確認する画面が表示されることがあります。そこで選んだ組織やプロジェクトが、URLへ指定したものと一致しているかを見ます。許可画面を閉じただけなら、登録は残っていてもツール呼び出しは完了しません。再接続を繰り返す前に、公式ドキュメントの接続状態と、自分のアカウントが対象プロジェクトを閲覧できる状態かを確かめます。出典: Supabase MCP Server公式ドキュメント。

Codexから見えるツールを確認する

接続後は、Codexに「利用できるSupabase MCPツール名を説明し、各ツールが読み取りか変更かを分類してください」と依頼します。いきなりSQLを実行するより、まずツールの種類を把握したほうが、質問の範囲を決めやすくなります。ツール一覧に変更系が見える場合は、開発用プロジェクトであっても、必要性を確認するまで呼び出さないよう依頼文に書きます。MCPサーバーの機能グループを絞った場合は、その設定と一覧が一致するかを見ます。

つながらないときの切り分け

接続に失敗したときは、同じコマンドを何度も試すより、どの段階で止まったかを確認します。登録コマンドが失敗したのか、登録後の許可画面で止まったのか、ツールは見えるが対象データの取得に失敗したのかで、見る場所が違います。エラーの全文、Codexの版、実行したディレクトリ、MCP名、URLから除いた機密値以外のパラメーターを記録しておくと、公式資料との照合がしやすくなります。

codex mcp add の段階で止まる場合

まず、コマンドの形を確認します。公式資料にある codex mcp add <name> --url <value> と、手元のCLIが表示するヘルプが一致しているかを見ます。URLを引用符で囲んでいない場合、PowerShellやシェルがクエリの記号を別の意味で解釈することがあります。参照IDの置き換え漏れ、改行の混入、名前の重複も登録失敗の原因になります。作業ディレクトリを変えても同じなら、ディレクトリではなくCLI版か設定の問題として切り分けます。

登録後の許可で止まる場合

ブラウザーの許可画面まで進んだ場合は、選択したアカウント、組織、プロジェクトを確認します。画面を閉じた、別アカウントで進めた、対象プロジェクトの閲覧権限がない、といった違いは、Codex側の登録成功とは別に起きます。いったん新しいプロジェクトへ接続し直す前に、Supabase公式画面で対象プロジェクトが開けるか、同じアカウントで表示されるかを確かめます。再接続を行う場合も、まず現在の登録名とURLを記録してから進めます。

ツールは見えるが結果が違う場合

ツール一覧が表示されても、目的のテーブルやログが見えない場合は、プロジェクト指定、機能グループ、データの存在、読み取り範囲の順に確認します。Codexへ別の言い方で同じ質問を重ねるだけでは、接続先の誤りは直りません。Supabaseの画面で対象プロジェクトを開き、参照IDとテーブル名を人が確かめ、その値をCodexの回答と比較します。結果が一致しない場合は、取得時点とフィルター条件も記録します。

Supabase MCPでCodexに頼む仕事の分け方

Supabase MCPが使えるようになった後も、依頼を大きくしすぎないことが大切です。MCPはデータや操作への入口を増やしますが、要件を決めたり、変更の正しさを保証したりする仕組みではありません。まず構造を読む、次に問題を絞る、その後に変更案を比べる、最後に人が適用結果を確認するという順番にすると、どの段階で誤りが入ったかを追いやすくなります。

構造を読む依頼

最初は、テーブル名、列、制約、マイグレーション履歴、関連するログなど、構造を説明できる範囲へ絞ります。「現在のプロジェクトにあるテーブルを一覧し、各テーブルの主な役割と、取得できなかった情報を説明してください」のように頼むと、Codexが見たものと見ていないものを分けやすくなります。個別のレコードを大量に返させるより、設計や調査の出発点を作る依頼のほうが、情報量を抑えながら確認できます。

読み取り中心の診断依頼

エラーを調べる場合は、対象期間、サービス、ログレベル、検索語を決めます。「直近のログをすべて取って」ではなく、「指定した時間帯のエラー件数を集計し、代表的なメッセージと参照した条件を示してください」と頼むほうが、結果を読み返しやすくなります。Codexの説明は診断の候補であり、原因確定ではありません。再現手順、アプリケーション側のログ、データベース側の状態を照合してから、次の調査へ進みます。

変更案を作る依頼

スキーマ変更を考えるときは、いきなり適用させず、まず案だけを作らせます。対象テーブル、既存データへの影響、NULLの扱い、インデックス、ロールバック方法、確認するテストを一つの説明に含めます。変更前の構造をMCPで確認したうえで、CodexにSQLやマイグレーションの候補を出させ、差分と実行条件を人が読みます。Supabase公式資料にある変更用ツールを使う場合も、開発用の対象で検証し、実行結果を記録してから次へ進めます。

Codex Plugin + MCPをどう使い分けるか

Supabaseの公式AI Toolsページには、MCPサーバー単体だけでなく、Codex Plugin + MCPという入口も掲載されています。ここで大切なのは、名前から機能を推測せず、現在の公式案内にある構成要素を確認することです。MCPはSupabaseへ接続する道具、追加の手順や知識をまとめたものは別の補助要素として扱い、どちらを導入したのかを記録します。出典: Supabase AI Tools公式ページ。

既にCodex CLIの設定を自分で管理している人は、まず公式MCP URLを一つ登録し、list と get、参照だけの質問で必要な範囲を確かめる方法が分かりやすいでしょう。一方、Supabase向けの案内、接続、補助資料をまとめて扱いたい場合は、公式ページに示されるCodex向け入口を確認し、手元のCodex版と提供条件が合うかを見ます。二つを同時に追加すると、どの設定がツールを表示したのか分からなくなるため、初回は一つずつ試します。

手動登録が向く場面

手動登録は、接続先を一つに限定したい、読み取り中心で試したい、機能グループを細かく管理したい場面に向いています。URL、登録日時、対象プロジェクト、機能、読み取り設定を記録できるため、変更前後を比較しやすいからです。小さな検証で結果を確認し、不要になったサーバー定義を整理するところまで含めて、自分の環境で再現できる形にしておきます。

公式のまとめ入口を確認する場面

SupabaseのAI ToolsページからCodex向けの入口を確認する方法は、Supabaseが案内する補助資料や対応範囲をまとめて見たいときに役立ちます。ただし、そのページに掲載されていることと、自分のCodex画面で同じ項目が使えることは同義ではありません。表示される版、選べるプロジェクト、追加されるツールを確認し、手動登録と同じく読み取りから始めます。

まとめ：Supabase MCPとCodexは範囲を決めてつなぐ

Supabase MCPとCodexの接続で大切なのは、設定コマンドを覚えることだけではありません。Supabase側で一つのプロジェクトを選び、必要な機能グループだけを有効にし、最初は読み取り中心のURLを使います。Codex側では codex mcp add で名前とURLを登録し、codex mcp list と codex mcp get で定義を確認します。その後、プロジェクト名、参照ID、テーブル一覧などを尋ね、実際の参照先が正しいかを確かめます。

接続後に変更を頼む場合は、構造の確認、変更案、影響の確認、開発用の検証、適用結果の確認を分けます。MCPが見えることは、すべての操作を許可する理由にはなりません。データの意味と変更の責任は人が持ち、Codexには取得した情報、使ったツール、未確認の項目を説明させます。

2026年9月17日時点で、Supabase公式のAI Tools一覧にはCodex Plugin + MCPが掲載され、OpenAI公式リファレンスにはMCPサーバーの登録と確認コマンドが案内されています。提供条件や画面が変わったときも、Supabase MCP公式ドキュメントとOpenAI Codex CLI公式リファレンスを起点に、接続先と確認結果を更新してください。