[Codex] Supabase MCPが起動しない原因はBearer Tokenの認証設定が不完全だったから

2026-02-09 mon

MCPとは

MCP（Model Context Protocol）は、AIモデルが外部ツールやデータソースに接続するための標準プロトコルである。AIクライアント（Codex, Claude Code, Cursor等）がMCPサーバー（Supabase, GitHub等）と通信することで、DB操作やドキュメント参照などの機能をAIから直接利用できるようになる。

CodexでSupabase MCPを使うには、codex mcp add コマンドで 接続先 URL と 認証に使う環境変数 を登録する必要がある。

CodexでSupabase MCPが起動しないエラーが発生した

Codex上でSupabase MCPを利用しようとしたところ、次のようなエラーが発生し、MCPが正常に起動しなかった。

初期に出ていたエラー（OAuth / 認証未設定）

⚠ MCP client for `supabase` failed to start:
MCP startup failed: handshaking with MCP server failed: Send
[rmcp::transport::worker::WorkerTransport<...>] error:
Auth error: OAuth token refresh
 
⚠ MCP startup incomplete (failed: supabase)

その後、設定を変更したあとには次のエラーに変化した。

変更後に出たエラー（401 Unauthorized）

⚠ MCP client for `supabase` failed to start:
MCP startup failed: handshaking with MCP server failed: Send message error Transport
[rmcp::transport::worker::WorkerTransport<...>] error:
Client error: HTTP status client error (401 for url
(https://mcp.supabase.com/mcp?project_ref=...),
when send initialize request
 
⚠ MCP startup incomplete (failed: supabase)

エラーメッセージだけを見ると「トークンが無効そう」「権限不足？」と考えてしまうが、根本原因は別のところにあった。

本当の原因：Bearer Tokenの認証設定が不完全だった（＋トークン自体も無効だった）

結論から言うと、原因は 2 つ重なっていた。

  1. MCP の認証設定（--bearer-token-env-var）が未設定 or 不完全だった
  2. SUPABASE_ACCESS_TOKEN に入っていたトークン自体も無効だった（失効・別アカウント・権限不足はいずれも該当せず、コピー不備の可能性が高い）

1つ目について、Supabase MCPの設定自体は存在していた（エラーに MCP client for 'supabase' と表示されていることから明らか）。しかし、Bearer Tokenとしてどの環境変数を使うかの設定（--bearer-token-env-var）が欠けていたため、認証が通らず起動に失敗していた。

codex mcp add supabase ... --bearer-token-env-var SUPABASE_ACCESS_TOKEN を実行して認証設定を正しく登録したところ、最初のエラーは解消した。

さらに2つ目として、認証設定を修正した後も401が継続していたため、トークンを再発行して差し替えたところ完全に解消した。

つまり、まず認証設定の不備が主因で、加えてトークン不備が追い打ちになっていた。

エラーの見え方としては「OAuth / 401」なのでトークンや権限を疑いやすいが、まず MCP の認証設定を確認するのが最優先。

確認方法

1) MCP認証設定の確認（最優先）

まず、Supabase MCPの認証設定が正しいかを確認する。

codex mcp list

OK な例（認証設定あり）：

Name                    Url
Bearer Token Env Var    Status    Auth
supabase                https://mcp.supabase.com/mcp?project_ref=...&read_only=true&features=docs%2Cdatabase%2Cdebugging%2Cdevelopment%2Cfunctions
SUPABASE_ACCESS_TOKEN   enabled   Bearer token

NG な例（認証未設定）：

Name                    Url
Bearer Token Env Var    Status    Auth
supabase                https://mcp.supabase.com/mcp?project_ref=...&read_only=true&features=docs%2Cdatabase%2Cdebugging%2Cdevelopment%2Cfunctions
-                       enabled   Unsupported

Bearer Token Env Var が - や空、Authが Unsupported になっていれば、認証設定が不完全。

2) 環境変数の確認

env | grep SUPABASE_ACCESS_TOKEN

OK な例：

SUPABASE_ACCESS_TOKEN=sbp_v0_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

何も表示されなければ環境変数が未設定。

3) トークン長の簡易チェック

printf '%s' "$SUPABASE_ACCESS_TOKEN" | wc -c

OK な例：

47

極端に短い場合は設定ミス（途中で切れている、改行が混ざっている等）の可能性が高い。ただし、今回のケースでは 47 文字と妥当な長さだったにもかかわらず401が出ていたため、長さだけでは正常性を保証できない。コピー時の文字化けや不可視文字の混入は長さに影響しない場合がある。

4) それでも401の場合：トークンが無効な可能性

認証設定が正しくても401が出続ける場合、トークン側の問題の可能性が高い。

今回のケースでは、失効・別アカウント・権限不足のいずれも該当しないことを確認済み。そのため、コピー時の末尾欠けや改行・空白の混入といったコピー不備が原因だった可能性が高い。

ただし、見た目では判別できないため、実務的には 新規発行して差し替えるのが最短。（今回も再発行で解決した。）

解決方法：Supabase MCPの認証設定を正しく行う

1. codex mcp add supabase で認証設定を登録する（最重要）

最も重要なのがこの手順。MCP設定が存在していても、--bearer-token-env-var が正しく設定されていなければ認証は通らない。

codex mcp add supabase \
  --url "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true&features=docs%2Cdatabase%2Cdebugging%2Cdevelopment%2Cfunctions" \
  --bearer-token-env-var SUPABASE_ACCESS_TOKEN

これにより、

  • Supabase MCPの接続先URL
  • Bearerトークンとして使う環境変数

がCodexに登録される。

2. SupabaseのPersonal Access Tokenを新規発行して差し替える

MCP登録後も401が出る場合は、トークン自体が無効の可能性がある。

以下のページから sbp_ で始まるPersonal Access Tokenを新規発行し、SUPABASE_ACCESS_TOKEN を差し替える。

3. .zshenv に環境変数を設定する

export SUPABASE_ACCESS_TOKEN='sbp_...'
source ~/.zshenv

.zshrc のみだと、非対話シェルで Codex に渡らないケースがあるため注意。

4. Codexを再起動する

設定変更後はCodexを再起動して反映させる。

補足事項

  • MCPの Never used 表示は問題ない
  • トークンを発行したアカウントがSupabaseプロジェクトに参加していない場合も401になる
  • エラーメッセージはOAuthや401を示すが、原因は MCP の認証設定不備のケースがある

まとめ

  • CodexでSupabase MCPを使うには codex mcp add supabase での認証設定（--bearer-token-env-var）が必須
  • MCP設定が存在していても、認証設定が不完全なら起動できない
  • 認証設定の修正後も401が続く場合は、トークン自体が無効の可能性がある（本件では失効・別アカウント・権限不足は否定でき、コピー不備の可能性が高かった）
  • 迷ったら トークンを新規発行して差し替えるのが最短
  • .zshenv にトークンを置くのが確実

「トークンの問題」に見えるエラーでも、認証設定の不備＋トークン不備の複合になっているケースがある。

参考リンク

関連記事