【2026年最新】Claude Code v2.1.238｜プラグイン配布認証

先週、受託開発で入っているクライアント先のプラットフォームチームから相談があった。「社内限定のClaude Codeプラグインを配布したいが、配布用のアーカイブURLにAPIキーをクエリパラメータで埋め込んでしまい、git historyに残ってしまった」という話だ。正直、これまでのClaude Codeのプラグイン配布は、社内限定gitリポジトリで公開範囲を絞るか、トークン付きURLを直書きするかの二択に近かった。v2.1.238（2026年8月20日リリース）のchangelogを読んで「これは使えるかもしれない」と思い、実装まで試した内容をまとめる。

2026年8月現在の結論 — v2.1.238で何が変わったか

Claude Code公式changelog（code.claude.com/docs/en/changelog）のv2.1.238（2026年8月20日）には、プラグインマーケットプレイス関連の変更として次の記述がある。

• 「Plugin marketplaces: headersHelper on a url marketplace or a catalog entry runs a command that mints HTTP headers (e.g. a short-lived token) for catalog and same-origin archive fetches」
• 「A catalog entry’s headersHelper runs only when you install or update that plugin, after its command is shown; claude plugin install/update ask [y/N] (or pass -y)」
• 「MCP headersHelper in a project .mcp.json, and inline MCP servers in project or --add-dir agent files, now require that folder’s trust dialog to have been accepted (also under claude -p)」
• 「MCP headersHelper from a project .mcp.json, plugin, or agent file runs without inherited credential env vars」

要するに、MCPサーバーの認証専用だったheadersHelperという仕組みが、プラグインマーケットプレイスの「カタログ（marketplace.json）取得」と「同一オリジンのarchive取得」にも使えるようになった、というのが今回のコア変更だ。

これまでのheadersHelperの仕組み（MCP認証の基礎）

headersHelper自体は新しい概念ではない。公式ドキュメント（code.claude.com/docs/en/mcp）によれば、Kerberosや短命トークン、社内SSOのようにOAuth以外の認証方式を使うMCPサーバーに対して、接続のたびにコマンドを実行してヘッダーを生成する仕組みとして以前から存在する。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

ヘルパースクリプトはヘッダーをJSON形式で標準出力に返す。

#!/bin/bash
echo "{"Authorization": "Bearer $(get-token)"}"

公式ドキュメントには「Claude Code runs the helper fresh on each connection, at session start and on reconnect. It doesn’t cache the result」と明記されている。つまりトークンの有効期限管理はヘルパースクリプト側の責任で、Claude Code本体はキャッシュしない。

v2.1.238での拡張ポイント3つ

公式changelogを実装観点で整理すると、変更点は次の3つに分解できる。

1. プラグインマーケットプレイスのカタログ・アーカイブ取得への適用

marketplace.jsonの取得（urlソースのマーケットプレイス）と、プラグイン本体を配布するarchiveソース（S3・Artifactory・nginx等でホストするzip配布、公式ドキュメントplugin-marketplacesで解説）の「同一オリジンからの」取得に、headersHelperで生成したヘッダーが使えるようになった。「same-origin」という制約が明記されている点は実装上重要で、マーケットプレイスのオリジンと異なるドメインのarchive URLには適用されない。

2. trust dialog必須化がclaude -p/SDKにも及ぶ

公式ドキュメントの更新差分には「Before v2.1.238, a claude -p or SDK session ran these helpers without checking trust, and an interactive session ran them once you had trusted a parent folder」という記述がある。つまりv2.1.237以前は、claude -p（非対話・スクリプト/CI実行）だとtrust dialogのチェックをスキップしてheadersHelperが動いていた。v2.1.238からはclaude -pでも同じtrust dialogの承認が必要になる。CI環境でこれまで無警告で動いていたheadersHelper付きMCPサーバーが、trust未承認のまま静的headersだけで接続される（＝認証ヘッダーが古いか空になる）可能性がある変更だ。

3. 認証情報env変数の非継承

「MCP headersHelper from a project .mcp.json, plugin, or agent file runs without inherited credential env vars」との記載どおり、他人が書いたリポジトリやプラグインが提供するheadersHelperは、あなたのANTHROPIC_API_KEYのような環境変数を読めない状態で実行される。ヘルパースクリプトが自前でトークンを発行できる設計（社内SSOやKMSからの都度取得）にしておく必要がある。

実装パターン：社内プライベートプラグイン配布をheadersHelperで守る

ここからは、社内向けのプライベートなプラグインマーケットプレイスを、静的トークンではなく短命トークンで守る実装パターンを組む。前提はClaude Code v2.1.238以上。

まず、marketplace.jsonのurlソースにヘルパーを設定する（公式ドキュメントのstrictKnownMarketplacesのurlソース記法に準拠）。

{
  "name": "internal-plugins",
  "owner": { "name": "platform-team" },
  "plugins": [
    {
      "name": "internal-code-review",
      "source": {
        "source": "archive",
        "url": "https://artifacts.internal.example.com/claude-plugins/code-review-2.3.0.zip"
      }
    }
  ]
}

このマーケットプレイスを社内メンバーに登録してもらう側（managed-settings.jsonや.claude/settings.json）でheadersHelperを指定する。

{
  "extraKnownMarketplaces": [
    {
      "source": "url",
      "url": "https://plugins.internal.example.com/marketplace.json",
      "headersHelper": "/opt/bin/get-plugin-registry-token.sh"
    }
  ]
}

トークン発行スクリプトは、ハードコードした秘密鍵ではなく、社内のOIDCやKMSから都度短命トークンを取得する構成にする。

#!/bin/bash
# /opt/bin/get-plugin-registry-token.sh
TOKEN=$(vault write -field=token auth/oidc/login role=cc-plugin-registry)
echo "{"Authorization": "Bearer ${TOKEN}"}"

これで、marketplace.jsonの取得と、同一オリジン（plugins.internal.example.com配下）のarchive取得の両方に、都度発行される短命トークンが使われる。artifacts.internal.example.comのように別ドメインにアーカイブを置く場合は「same-origin」の制約に当たるため、マーケットプレイスとarchiveを同一オリジンに揃えるか、別途アーカイブ側の認証を設計する必要がある。

移行手順（5ステップ）

1. バージョン確認 — claude --versionで2.1.238以上か確認する。未満ならclaude update（または配布パッケージの更新）で上げる
2. 既存headersHelperの棚卸し — 社内の.mcp.json・managed-settings.json・プラグインmanifestにheadersHelperを使っている箇所を洗い出す
3. CI（claude -p）での接続確認 — trust dialog承認が必要になった対象フォルダを、CIのワークスペース設定やmanaged-settingsの許可リストに明示的に加える
4. ヘルパースクリプトの実行環境を再確認 — 認証情報env変数が非継承になったため、ヘルパー内で環境変数依存の認証をしていないか確認し、必要ならヘルパー自身がトークン発行元（Vault/KMS/社内SSO）に直接問い合わせる形に書き換える
5. プラグインマーケットプレイスへの適用を検討 — 社内配布プラグインがある場合、静的トークンのURL埋め込みをheadersHelper方式に置き換える

導入前後の比較表

項目	v2.1.237以前	v2.1.238以降
プラグインマーケットプレイスの認証	URLへのトークン埋め込み、または非公開gitリポジトリでの範囲限定のみ	headersHelperでカタログ・同一オリジンarchive取得時に短命トークンを動的発行可能
claude -p実行時のheadersHelper	trust dialogチェックなしで実行される	対話セッションと同じtrust dialog承認が必須
ヘルパーに渡る環境変数	ANTHROPIC_API_KEY等を含む実行環境の変数が継承される	プロジェクト.mcp.json・プラグイン・agentファイル由来のヘルパーには認証情報env変数が継承されない
インストール/更新時の確認	MCPのheadersHelperには専用の確認プロンプトなし	プラグインのheadersHelperはコマンド内容を表示し[y/N]確認（-yで省略可）

失敗パターン4つ

実装中に踏んだ、あるいは踏みそうになった落とし穴を❌⭕形式でまとめる。

❌ CIのclaude -p実行環境で、trust dialog未承認のままheadersHelper付きMCPサーバーを使い続けて「認証ヘッダーが更新されず401が出る」原因を調査していた
⭕ v2.1.238のchangelogで「claude -pもtrust dialog対象になった」と分かってからは、CIのワークスペース設定でフォルダを明示的にtrust済みとして登録する運用に変えた

❌ マーケットプレイスのarchiveを別ドメインのCDNに置いたままheadersHelperを設定し、「same-origin」の制約を見落として認証ヘッダーが付かない状態で放置していた
⭕ マーケットプレイスのカタログとarchiveを同一オリジン（同じサブドメイン配下）に揃えて配布する構成に統一した

❌ ヘルパースクリプトの中で、実行環境のANTHROPIC_API_KEYを使い回して社内APIの認証をしようとしていた（プラグイン提供のヘルパーには継承されない前提を知らなかった）
⭕ ヘルパースクリプトは環境変数に依存せず、設定ファイルまたはVault等のトークン発行元へ都度アクセスする形に書き換えた

❌ claude plugin install時に出る[y/N]確認を、CIの非TTY実行で毎回手動待ちにしてパイプラインを止めていた
⭕ 公式ドキュメントの案内どおり-y/--yesフラグを付け、「Claude Code still prints the command first」の通りログにコマンド内容だけは残す運用にした

実装で気づいたこと（個人エピソード）

1つ目。最初は「headersHelperをMCPからプラグインマーケットプレイスに転用するだけ」と軽く考えていたが、「same-origin」という制約を読み飛ばしていて、検証環境でarchiveのドメインだけ別に切っていたため認証ヘッダーが付かず、しばらく403の原因を追いかけることになった。changelogの一文一文を実装前にちゃんと読む重要性を再確認した。

2つ目。trust dialogの挙動がCIで変わる、という変更は地味だが実害が大きい。うちの場合はCI用のワークスペースディレクトリをmanaged-settingsの許可リストに載せていなかったので、v2.1.238にアップデートした直後にheadersHelper付きのMCPサーバーが静的headersのみで接続されるようになり、社内APIから401が返る障害を一度出した。バージョンアップ後の変更点は「新機能」だけでなく「既存動作の前提が変わる箇所」も必ず確認する必要がある。

3つ目。ヘルパースクリプトに環境変数を渡さない設計は、最初は不便に感じたが、よく考えれば妥当な変更だ。社外のプラグインやリポジトリが提供するheadersHelperは、書いた人が信頼できるかどうかわからない任意のシェルコマンドである。自分のANTHROPIC_API_KEYを渡さない前提で設計されているのは、単純にセキュリティ上の防御が一段上がったということだと理解した。

SaaS・ITの適用余地と他業種への展開

今回の変更が最も刺さるのは、複数チーム・複数プロダクトを抱えるSaaS・IT企業のプラットフォームエンジニアリング組織だ。社内向けの共通プラグイン（コードレビュー規約、社内API連携、Lintルールなど）を配布する際、これまでは「非公開gitリポジトリでアクセス制御する」か「配布URLにトークンを埋め込む」の二択だった。headersHelperを使えば、配布そのものは静的ファイルサーバー（S3・Artifactory・nginx）に置きつつ、認証だけを短命トークンで動的に守れる。

金融・医療のように監査要件が厳しい業界でも、「誰が・いつ・どのプラグインを取得したか」をトークン発行側（Vault・KMS・社内SSO）のログとして残せる点は、静的トークンの埋め込みより監査適合性が高い。ただし、今回の対象範囲はあくまで「マーケットプレイスのカタログ」と「同一オリジンのarchive取得」に限定される点は、設計時に必ず確認したほうがいい。

Claude Codeに投げたプロンプト例

実装中に実際に使ったプロンプトを5つ挙げる。

1. 「社内プラグイン配布用のmarketplace.jsonのarchiveソースを、Vault経由の短命トークンで認証する構成に書き換えて。トークン発行スクリプトも一緒に作って」
2. 「headersHelperスクリプトの中でANTHROPIC_API_KEYのような環境変数を参照している箇所がないかレビューして」
3. 「claude -pで動かしているCIパイプラインが、v2.1.238のtrust dialog必須化の影響を受けそうな設定ファイルを洗い出して」
4. 「marketplace.jsonのarchiveとカタログのオリジンが一致しているか、この設定ファイルから確認して」
5. 「-y/–yesフラグを使ってCIでの非対話インストールに対応したデプロイスクリプトのサンプルを書いて」

FAQ

Q. headersHelperは無料枠でも使えますか？
A. headersHelperはClaude Code CLI自体の機能であり、契約プランによらず利用できる。ただし発行するトークンの発行元（Vault・KMS・社内SSO等）は別途自前で用意する必要がある。

Q. 既存のURL埋め込みトークン方式はすぐ動かなくなりますか？
A. v2.1.238はheadersHelperの適用範囲を広げる追加機能であり、既存の静的トークン埋め込み方式自体を廃止するものではない。ただし、URLに秘密情報を含める方式はgit historyやログに残るリスクが高く、順次移行を検討したほうがよい。

Q. archiveが別ドメインでもheadersHelperのヘッダーは付きますか？
A. 公式changelogの記載どおり「same-origin」が条件であり、マーケットプレイスのカタログと異なるオリジンのarchiveには適用されない。別ドメインで配布する場合は、そのファイルサーバー側の認証方式を別途設計する必要がある。

Q. claude -pで動かしているCIが急に401になったら、まず何を確認すればいいですか？
A. v2.1.238以降でtrust dialog承認がclaude -pにも必須になったため、CIのワークスペースディレクトリがtrust済みとして扱われているかを最初に確認する。managed-settingsやプロジェクト設定の許可リストへの追加で解消するケースが多い。

まとめ・今日やること

v2.1.238の変更は、派手な新機能というより「既存のheadersHelperという認証プリミティブの適用範囲拡大」と「trust dialogの一貫性強化」だ。社内向けにプラグインやMCPサーバーを配布しているなら、まずはclaude --versionでバージョンを確認し、CI（claude -p）実行環境でtrust dialog未承認による認証ヘッダー欠落が起きていないかを確認するところから始めるといい。

出典・参照ソース

• Claude Code Changelog v2.1.238（2026年8月20日） — code.claude.com/docs/en/changelog
• Connect Claude Code to tools via MCP（headersHelperの基本仕様・trust dialog要件） — code.claude.com/docs/en/mcp
• Create and distribute a plugin marketplace（url/archiveソースの仕様） — code.claude.com/docs/en/plugin-marketplaces
• Plugins reference（claude plugin install/updateの-y/–yesフラグ仕様） — code.claude.com/docs/en/plugins-reference

関連記事: 【2026年最新】自動医療コーディング支援｜Claude Code実装ガイド

あわせて読みたい

• ▸ 【2026年9月】Claude Code研修・講師の依頼先6社比較と選び方
• ▸ 【2026年最新】Claude Code /compact｜長時間開発の5手順
• ▸ 【2026年最新】Claude Code /diff活用｜差分レビュー5手順
• ▸ 【2026年最新】Claude Code管理MCP配布｜7手順
• ▸ 【2026年最新】Claude Code外部読取制御｜設定5手順