サンドボックスCodexCLIにsupabaseMCP 導入で苦戦した原因
以下は、今回の一連のトラブルシュートを踏まえてまとめた実運用レポートです。環境固有の要因→失敗要因→成功の決め手→再発防止の指針→CodexCLIの作法→他MCPへの展開、の順で整理しました。
- 現在の環境“独特”の問題点（WSL + Codex の合わせ技）
WSL2 + Codex サンドボックス
Codex はデフォルトで外部コマンドをサンドボックス内で走らせます。書込み先（~/.mcpt など）やネットワークの扱いが通常 Linux と異なり、外部CLIに頼るフローは詰まりやすい。
/mcp はCodex のTUI内部コマンド。Bash に打つと失敗します（/mcp: No such file など）。
WSL Interop / 既定ブラウザ
wslview が使えないと OAuth 認可URLを開けません。今回、Interop 有効化と BROWSER=wslview で解決。
PATH・権限・ディレクトリ
~/go/bin の mcp CLI、npx/pnpm dlx の毎回ダウンロード、~/.mcpt への書込み不可など、外部CLI系の摩擦が大きい。
TOML 記述の落とし穴
args = ["-lc", "<長いコマンド>"] を複数行や末尾 \ で書くと TOML パースエラー（missing comma between array elements）。
- supabaseMCP 導入に長期で苦戦した“本質的”原因
経路の混同（HTTP+OAuth vs STDIO）
「リモートMCP（URL+OAuth）」と「ローカルMCP（STDIO）」の2経路が同時に存在。さらに Codex が思考過程で外部CLI（mcp/npx）へフォールバックしやすく、OAuth が一度も発火しない状態が続いた。
外部CLIフォールバックの連鎖
mcp alias・mcp tools・npx @supabase/mcp-server-supabase に落ちるたび、
ネットワーク制約で初期化タイムアウト
~/.mcpt permission denied
execute_sql: not found（シェルコマンド扱い）
npm EACCES / semver “Invalid Version”
が発生し、再試行のたびに別の壁へ誘導された。
環境変数の受け渡しミス
.env に PAT はあるのに、Codex → MCPサーバ起動時に SUPABASE_ACCESS_TOKEN が注入されない（親環境が空だと env = { ... } が空注入）→ Unauthorized 連発。
TOML 設定と操作の勘所
/mcp call … を Bash 側で実行したり、TOML の args を複数行にして構文エラー。
- 今回「成功した」理由・気付き（決定打）
STDIO 方式に一本化し、外部CLIの不確実さ（npx/pnpm）を排除
@supabase/mcp-server-supabase を グローバルに固定インストール → 絶対パス起動に変更。
同一コマンドとして認識されるため、承認は初回のみで済む。
.env を MCP サーバ起動“直前”に確実ロード
Codex 設定を command = "bash" + args = ["-lc", "set -a; . .env; exec mcp-server-supabase ..."] に変更。
親環境が空でも サーバープロセスには必ずPATが入る → Unauthorized 解消。
ランチャー（codex-supabase）で起動を標準化
毎回 .env の export を忘れない・プロファイルや sandbox を間違えない・PATH の差異で迷わない。
/mcp は TUI内のみという作法の徹底
Bashに /mcp を打たない。自然言語でツール実行を指示する、が最も安定。
- 成功のために行った“工夫”一覧（そのまま運用Tips）
固定インストール + 絶対パス
npm i -g @supabase/mcp-server-supabase@0.5.6
command -v mcp-server-supabase # → 絶対パスを config に記入
Codex 設定（抜粋：TOMLは1行で書く）
sandbox_mode = "workspace-write"
approval_policy = "untrusted"
[sandbox_workspace_write]
network_access = true
[mcp_servers.supabase]
command = "bash"
args = ["-lc", "set -a; [ -f $HOME/projects/_xxx/.env ] && . $HOME/projects/_xxx/.env; set +a; exec /home/fire/.npm-global/bin/mcp-server-supabase --read-only --project-ref=_xxx"]
startup_timeout_sec = 300
tool_timeout_sec = 90
ランチャーで .env 自動ロード
~/bin/codex-supabase
#!/usr/bin/env bash
cd "$HOME/projects/_xxx" || exit 1
set -a; [ -f ./.env ] && . ./.env; set +a
exec codex --sandbox workspace-write --ask-for-approval untrusted "$@"
承認は“この1本だけ二度と聞かない”
初回の「bash -lc ... mcp-server-supabase ... を実行しますか？」→ Don’t ask again。
WSL Interop の徹底確認（wslview / cmd.exe /c ver）
OAuth方式を使うときは必須（今回はSTDIOだが将来のため）。
- 改めて：CodexCLI の使い方（要点のみ）
/mcp は TUI内の“表示”コマンド
/mcp：MCP サーバ一覧表示。
/mcpに引数はない。実行は自然言語で「◯◯ MCP の △△ を実行して」と指示する。
実行の正攻法
「Supabase MCP の execute_sql で “…SQL…” を実行して」
外部CLI（mcp/npx/curl）を提案されたら拒否し、「shell ではなく設定済みの MCP で」と明言。
サンドボックスと承認
workspace-write + network_access=true（セッション単位）。
untrusted で都度確認→必要なものだけAllowlistへ。
環境変数の受け渡し
最小トラブルは bash -lc で .env を起動直前に source。
config.toml に秘密の“値”は直書きしない（どうしても検証で書いたら、直後にローテーション）。
- 他の MCP 導入にも効く“再現性の高いプラクティス”
A. まずはSTDIO 方式で安定させる
固定インストール → 絶対パス → bash -lc で .env を確実注入
テンプレ（置換して使用）：
[mcp_servers.<name>]
command = "bash"
args = ["-lc", "set -a; [ -f $HOME/<project>/.env ] && . $HOME/<project>/.env; set +a; exec </絶対パス/サーバ実行ファイル> <必要な引数>"]
startup_timeout_sec = 300
tool_timeout_sec = 90
Allowlist：サーバ起動だけ「今後聞かない」に。
B. その後、HTTP+OAuth 方式へ段階的に移行（必要な場合）
名前分離：<name>-remote にして衝突回避。
外部CLIのPATH退避（codex-safe ランチャ）でフォールバック遮断。
実ツール実行を1回 → 認証URLが出る → wslview で開く → /mcp に Tools が並ぶことを確認。
C. 失敗モード → 即手当の早見表
症状 代表ログ・現象 処置
OAuth が出ない Tools: (none) のまま / 外部CLI提案が出る 外部CLI拒否、名前分離（-remote）、codex-safe で PATH から mcp を外す
Unauthorized Please provide access token … bash -lc で .env を起動直前に source、PAT 直書きは避ける
execute_sql: not found exec: "execute_sql": not found 外部 mcp CLI に逸れている。**自然言語で“設定済みMCPで”**を明示
TOML エラー missing comma ... args の 2要素目は1行で書く。改行・\禁止
初期化 timeout npx/pnpm で時間切れ 固定インストール + 絶対パス、startup_timeout_sec を延長
7. 今回の“最終形”サマリ（保存版）
起動：codex-supabase（.env 自動ロード）
Config（要部）：
[mcp_servers.supabase]
command = "bash"
args = ["-lc", "set -a; [ -f $HOME/projects/_xxx/.env ] && . $HOME/projects/_xxx/.env; set +a; exec /home/fire/.npm-global/bin/mcp-server-supabase --read-only --project-ref=_xxx"]
startup_timeout_sec = 300
tool_timeout_sec = 90
実行の仕方：TUIで
「Supabase MCP の execute_sql で “…SQL…” を実行して」
- 最後に（推奨アクション）
PAT のローテーション（ログに出たため）→ .env 更新。
Serena の安定化は、単体ウォームアップ + startup_timeout_sec 延長で対応。
運用テンプレ（スキーマ点検、サイズ上位、FK/RLS、インデックス診断、孤児行チェック等）をそのまま貼って使える形で整備。
これで **「なぜ苦戦したか／なぜ成功したか／今後どうすべきか」が一本の手順にまとまりました。
他の MCP を追加する際も、「STDIOで安定→必要ならHTTP+OAuthへ」**の手順で愚直に進めば、同種のハマりを避けられます。
Discussion