Claude Code と Codex の両方に1つの plugin ディレクトリで対応する場合、同梱する MCP サーバー設定は単一ファイルの共有ではなく、クライアント別ファイルへの分離が必要になる。2026-07 時点の実測に基づく。

前提となる挙動（実測）

• Codex は Claude plugin 形式（.claude-plugin 配下の marketplace.json / plugin.json）をそのままマーケットプレイス追加・インストールできる。互換は高いが、以下の2点で単一設定の共有が破綻する。
• Codex は MCP 設定内の user_config プレースホルダーを展開しない。生文字列のまま接続先に送るため、URL クエリに埋めているとサーバー側の形式バリデーションで弾かれる壊れ方をする。
• Claude はマニフェストで指定した MCP 設定ファイルと、plugin ルートの既定 .mcp.json を置換ではなくマージして両方読む。両方置くと同じサーバーが二重登録される。

構成の判断基準

• plugin ルートに既定の .mcp.json を置かない。
• .claude-plugin と .codex-plugin の両マニフェストに、それぞれ専用の MCP 設定ファイル（例: mcp ディレクトリ配下に claude 用と codex 用）を mcpServers フィールドで指定する。
• user_config などクライアント固有の展開記法は、そのクライアント用のファイルだけに置く。展開非対応のクライアント用には静的な値（またはパラメータなしの URL）を置く。

同名サーバーの衝突挙動（利用者案内に必要）

• Claude: plugin 同梱サーバーは「plugin:プラグイン名:サーバー名」という名前空間で登録され、利用者が手動設定した同名サーバーと衝突せず共存する。両方を認証すると同じツールが2セット現れてコンテキストを圧迫するため、配布側は「手動設定済みならどちらか一方」と案内する。
• Codex: 同名なら既存のユーザー設定が勝ち、plugin 側は黙ってスキップされる。既存利用者を壊さない一方、plugin 側の設定が効いていないことに気づきにくい。

検証方法

両 CLI の MCP サーバー一覧表示で、(1) プレースホルダーが展開済みかを URL 表示で確認、(2) 同名サーバーを手動設定と plugin の両方に置いて登録結果（共存かスキップか）を確認する。