Claude CodeでUnleash MCPを使い、フィーチャーフラグを作成から整理まで管理する

Unleash公式のMCPサーバー(@unleash/mcp)をClaude Codeに登録すると、コード変更にフラグが要るかの判定、フラグの作成、ガード用コードの生成、ロールアウトの設定、後片付けまでを会話で進められます。登録はclaude mcp addの1コマンドです。ただし同じ入口から、環境ごとの有効・無効の切り替えもできてしまいます。接続の手順と合わせて、本番を守る権限設定とCLAUDE.mdの書き方まで押さえます。

何ができるか — 5つの用途と12のツール

Unleash MCPサーバーは、Unleash Admin APIを呼ぶツールを用途別に束ねたものです。用途は次の5つに分かれます。

Claude Code向けの案内にも同じ12ツールが並びます。流れは「評価 → 重複検出 → 作成 → ラップ」です。evaluate_changeが必要と判断すると、create_flagとwrap_changeを順に呼ぶよう指示が返ります。detect_flagは評価の中で自動的に走り、近いフラグがあれば再利用を提案します。

見落としやすいのは、書き込みの重さがツールごとに違う点です。create_flagは作成したフラグを無効の状態で置きます。cleanup_flagは削除を実行せず、フラグが使われているファイルと行番号、残すべき分岐、実行すべきテストを返すだけです。実際に環境へ影響するのはtoggle_flag_environment、set_flag_rollout、remove_flag_strategyの3つになります。権限設定の話は後半でこの3つを軸にします。

事前に用意するもの

local(stdio)で動かす場合の前提は次の4点です。

• Node.js 18以上(npxで@unleash/mcpを起動するため)
• Claude Code
• Unleashのインスタンス(ホスト型でもセルフホストでも可)
• フラグを作成できる権限を持つ個人アクセストークン(PAT)

接続に使う環境変数は3つです。UNLEASH_BASE_URLとUNLEASH_PATは必須で、UNLEASH_DEFAULT_PROJECTは任意です。デフォルトのプロジェクトを省くと、ツールを呼ぶたびにprojectIdを指定する形になります。

接続する — 1コマンドの登録とチーム共有の登録

まず試すだけなら1コマンド

プロジェクトのルートで次を実行します。最短の形です。

claude mcp add unleash \
    --env UNLEASH_BASE_URL=https://your-instance.example.com \
    --env UNLEASH_PAT=your-personal-access-token \
    -- npx -y @unleash/mcp@latest --log-level error

--より後ろはサーバーの起動コマンドで、Claude Codeは手を加えずそのまま渡します。この設定はプロジェクトのパス単位で保存されるので、使いたいプロジェクトのルートで実行します。

ただしこの形はPATを引数に直書きします。シェルの履歴に残りますし、設定ファイルにも値そのものが入ります。個人の検証にとどめ、チームで使うなら次の形にします。

チームで使うなら環境変数参照にする

認証情報は別ファイルに置き、シェルの起動ファイルから読み込む構成にします。

mkdir -p ~/.unleash
cat > ~/.unleash/mcp.env << 'EOF'
UNLEASH_BASE_URL=https://your-instance.getunleash.io
UNLEASH_PAT=your-personal-access-token
UNLEASH_DEFAULT_PROJECT=default
EOF
chmod 600 ~/.unleash/mcp.env

~/.zshrcまたは~/.bashrcに、このファイルをsourceして3変数をexportする数行を足し、シェルを開き直します。そのうえで、プロジェクトスコープで登録します。

claude mcp add --transport stdio --scope project unleash \
  -e UNLEASH_BASE_URL='${UNLEASH_BASE_URL}' \
     UNLEASH_PAT='${UNLEASH_PAT}' \
     UNLEASH_DEFAULT_PROJECT='${UNLEASH_DEFAULT_PROJECT:-default}' \
  -- npx -y @unleash/mcp@latest --log-level error

値を単引用符で囲むのが肝です。囲まないとシェルが登録時に展開してしまい、PATが設定ファイルに焼き込まれます。単引用符なら${...}の文字列がそのまま残り、Claude Codeが起動時に展開します。結果として、プロジェクト直下に次の.mcp.jsonができます。

{
  "mcpServers": {
    "unleash": {
      "command": "npx",
      "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"],
      "env": {
        "UNLEASH_BASE_URL": "${UNLEASH_BASE_URL}",
        "UNLEASH_PAT": "${UNLEASH_PAT}",
        "UNLEASH_DEFAULT_PROJECT": "${UNLEASH_DEFAULT_PROJECT:-default}"
      }
    }
  }
}

トークンの値は含まれないので、リポジトリにコミットしてチームで共有できます。${VAR:-default}は、変数が未設定のときに既定値を使う書式です。変数名を書いて未設定かつ既定値もない場合、Claude Codeはclaude mcp listと/mcpに警告を出し、${VAR}の文字列のまま起動します。設定忘れは警告で気づけます。

プロジェクトスコープの.mcp.jsonは、利用側の初回に承認が求められます。クローンしただけでは接続されず、claude mcp listでは承認待ちと表示されます。claudeを対話で起動して承認してください。

接続を確かめる

claude mcp get unleash

登録名、種別がstdioであること、起動コマンド、スコープが出ます。セッション内では/mcpで接続中のサーバーとツールを見られます。ツールが出ないときは、次の順で切り分けます。

1. claude mcp listでサーバーが登録されているか見る
2. echo $UNLEASH_BASE_URLで変数がexportされているか見る
3. curl -H "Authorization: $UNLEASH_PAT" "$UNLEASH_BASE_URL/api/admin/projects"で認証情報を直接試す
4. シェルの起動ファイルを直したなら、ターミナルを開き直す

認証エラーでは、UNLEASH_BASE_URLの末尾に/apiを付けていないかも確かめます。ネイティブのWindowsではnpxを直接渡せず、cmd /cで包みます。

日々の使い方 — 会話で進める4つの場面

依頼文の例を並べます。返ってくる出力は環境とバージョンで変わります。

変更にフラグが要るかを判定する

Evaluate whether replacing the payment library should be behind a feature flag.
The change modifies src/payments/.

evaluate_changeは、変更内容のリスクを点数で見積もります。クリティカル(+5)は認証・決済・セキュリティ・データベース操作、高(+3)はAPI変更・外部サービス・新しいクラス、中(+2)は非同期処理・状態管理、低(+1)はバグ修正・リファクタ・小さな変更です。親フラグの検出も行い、すでにフラグで守られたコードへ入れ子にするのを避けます。返り値にはneedsFlag、recommendation、suggestedFlag、riskLevelなどが入ります。riskLevelとdescriptionを自分で渡すと、判断材料が増えて提案の精度が上がります。

重複を避けて作成し、コードを包む

detect_flagは、編集中のファイル、gitの履歴、説明文と既存フラグ名の意味的な近さ、周辺コードの4つの手がかりを組み合わせます。確信度が0.7以上なら再利用を勧め、0.4から0.7は人が見て決める帯、0.4未満は新規作成寄りです。該当がなければcreate_flagの出番で、name・type・descriptionが必須です。

typeは5種類から選びます。

• release: 段階的な機能公開
• experiment: A/Bテスト
• operational: システム挙動の切り替え
• kill-switch: 緊急停止
• permission: 役割や権利に応じたアクセス制御

作成後、wrap_changeが言語とフレームワークに合ったガード用コードの雛形を返します。対応言語はTypeScript・JavaScript・Python・Go・Ruby・PHP・C#・Java・Rustです。フレームワークはframeworkHintで指定でき、ReactやExpress、Django、Rails、Spring Bootなどを渡せます。既存コードのフラグの使い方を検索する手順も返すので、リポジトリの流儀に寄せて書かせられます。

ステージングで有効にし、段階的に広げる

Enable stripe-payment-integration in the staging environment.

Set up a gradual rollout for stripe-payment-integration:
10% for 24 hours, then 50% for 48 hours, then 100%.

前者はtoggle_flag_environment、後者はset_flag_rolloutが受けます。状態の確認はget_flag_stateで、メタデータ・有効な環境・戦略が返ります。

展開後に片付ける

Clean up the stripe-payment-integration flag. The feature is fully rolled out.

cleanup_flagは、フラグの参照箇所を洗い出し、残すべき分岐(有効側)と確認用のテストを示します。条件分岐を外す編集はClaude Code側で行い、Unleash上のフラグのアーカイブや削除は自分で進める流れです。棚卸しだけをしたいときは、list_flagsを有効側とアーカイブ側で2回呼びます。2つの結果は重ならないため、一覧を完全にするには両方が要ります。コード内の参照と突き合わせれば、使われていないフラグが見つかります。

本番を守る — 権限ルールと変更リクエストの二重にする

AIアシスタントは、間違った環境や間違ったフラグを切り替えることがあります。対策は2層で考えます。

Unleash側: 本番環境で変更リクエストを有効にする

環境で変更リクエスト(change requests)を有効にすると、MCPサーバーは変更を直接適用せず、変更リクエストとして送ります。人が承認するまで反映されません。誤操作を防ぐ効果はClaude Codeの設定より強く、人の手による操作にも同じ仕組みが効きます。本番では有効にする前提にしておくのが無難です。

Claude Code側: 影響のある3ツールに確認を挟む

MCPツールの権限名はmcp__<サーバー名>__<ツール名>です。サーバー名をunleashで登録した場合、環境に影響する3ツールは次のように書けます。.claude/settings.jsonに入れます。

{
  "permissions": {
    "ask": [
      "mcp__unleash__toggle_flag_environment",
      "mcp__unleash__set_flag_rollout",
      "mcp__unleash__remove_flag_strategy"
    ]
  }
}

これで3ツールは呼ばれるたびに承認が求められ、評価・検出・一覧・状態確認といった読み取り寄りの操作は止まりません。なおmcp__unleash__*のようにサーバー全体を許可するルールは、mcp__unleash__の後ろでのみワイルドカードが使えます。allowとaskは併用でき、評価はdeny、ask、allowの順に進むため、allowにサーバー全体を入れても、askに書いた3ツールには確認が出ます。権限記法の全体はMCP権限ルールの書き方にまとめています。実行系のツールにだけ確認を挟む同じ考え方は、Hostinger MCPの記事でもドメイン購入の事故防止に使っています。フィーチャーフラグをCI/CDと一緒にClaude Desktopから扱いたい場合は、CloudBees Unifyコネクタという別の選択肢もあります。

CLAUDE.mdに運用ルールを書く

フラグの命名や種類、クリーンアップの時期は、会話のたびに伝えるとぶれます。CLAUDE.mdに書いておけば、Claude Codeが毎回読み込みます。Unleashの基本テンプレートを縮めた例です。

## フィーチャーフラグの扱い
 
- 決済・認証・データ移行・外部連携を変更する前に、Unleash MCPの
  evaluate_changeでフラグの要否を判定する
- フラグ名は `{ドメイン}-{機能}-{バリアント}` の形式にする
  (例: checkout-stripe-integration)
- 新規作成の前に必ず detect_flag で既存フラグを確認する
- 100% になって2週間を過ぎたフラグは cleanup_flag で整理する
- 本番環境の変更はこのセッションでは行わず、手順だけ提示する

応用として、ドメインごとのルール(決済は常にフラグ必須、UI部品はスタイルなら任意など)や、ロールアウトの既定(10%から始め、24時間待ち、エラー率が1%を超えたら止める)も書けます。この数値はドキュメントの例であって、Unleash側に組み込まれた設定ではありません。自チームの基準に置き換えてください。

CLAUDE.mdは助言であって強制力はないので、実際に止めたい操作は上のaskで押さえます。「ルールで書く層」と「権限で止める層」の両方を置く考え方です。

パイプで回す — レビューと棚卸しの自動化

非対話のclaude -pを使うと、既存のコマンドと組み合わせられます。例を示します。

git diff main...feature-branch | claude -p \
  "Analyze this diff. Use evaluate_change to determine which changes need feature flags."

同様に、直近のコミットをevaluate_changeにかけて「フラグが要ったはずの変更」を洗い出す使い方や、ステージング済みの差分を評価するコミット前フックも組めます。非対話実行ではツールの承認を答えられる人がいないため、前述のaskに当たるツールは動かせません。自動化には読み取り中心の用途を選ぶと安全です。

リモートMCPサーバーという選択肢

開発者のPCにMCPサーバーを入れられない組織向けに、Unleashインスタンスがホストする方式もあります。Enterpriseの機能で、エンドポイントはhttps://<インスタンス>/api/admin/mcpです。ツールはローカル版と同じです。有効化は管理画面の「Admin settings > Remote MCP server」で行い、セルフホストでは先にUNLEASH_EXPERIMENTAL_REMOTE_MCP_SERVER=trueを設定して再起動します。

Claude Codeからの接続は、HTTPトランスポートで登録します。

claude mcp add --transport http unleash https://<インスタンス>/api/admin/mcp

登録後、/mcpでunleashを選んでログインします。ブラウザログインでは24時間有効のPATが発行され、以後の通信に使われます。ログイン後のリダイレクト先がlocalhostに限られるため、Claude Codeのようなコマンドライン型のクライアントでは使えますが、Claude Desktopやブラウザ上のClaudeでは使えません。トークンの期限を自分で管理したいときは、--header "Authorization: Bearer <トークン>"を付けて登録します。

導入前に確認する点が1つあります。Claude Codeは事前登録されたOAuthクライアントを持たないため、動的クライアント登録(DCR)を許可しないと接続できません。DCRはクライアントが管理者の承認なしに自己登録できる方式なので、有効にする前に組織のポリシーを確認してください。

フィードバック送信の既定を決めておく

send_feedbackは、ツールのエラーや未対応の依頼、想定外の結果を、アシスタントが匿名の診断レポートとして送るツールです(MCPのv0.5.0以降、ベータ)。ローカル版は同意を取ってから送ります。初回に同意の確認が出て、承諾か拒否かが保存されます。送られる内容はエラー種別・ツール名・正規化されたエラーコード・MCPとクライアントのバージョン・アシスタントが書く短い要約に限られ、PATや生のエラーメッセージは含まれません。

確認の表示を出したくないときは、環境変数UNLEASH_MCP_SEND_FEEDBACKをtrueかfalseにします。組織全体で固定するなら、管理MCP設定(managed-mcp.json)のenvに入れます。falseにするとツール自体が見えなくなります。送り先を自社のエンドポイントに変えるUNLEASH_FEEDBACK_URLもあります。

うまくいかないとき

エラーコードの意味は次のとおりです。

サーバーが繰り返し落ちた場合、Claude Codeは自動で再起動を試み、失敗が続くとそのセッションでは無効にします。認証情報を直してからClaude Codeを再起動してください。ツールの結果が途中で切れるときは、プロジェクトやフラグの種類で絞り込んで件数を減らします。

運用の型として押さえたいこと

Unleash MCPの価値は、フラグの作成そのものより、変更のたびに「フラグが要るか」を問う習慣をClaude Codeに持たせられることにあります。型としては次の3段です。

1. CLAUDE.mdで命名と判断基準を固定する
2. askで環境に影響する3ツールを止める
3. 本番では変更リクエストを有効にし、最終承認を人に残す

フラグは一時的なものとして扱い、cleanup_flagを定期的に回せば、削除し忘れた古いフラグがコードに溜まるのを抑えられます。