Cannot add MCP server to scope: managedの原因と対処
claude mcp addに--scope managedを付けると出るエラーの原因は、managedスコープが管理設定からしか読まれない領域だからです。書き込める3スコープと、管理者向けmanagedMcpServersの書き方です。
claude mcp addやclaude mcp add-jsonに--scope managedを付けると、Cannot add MCP server to scope: managedというエラーで止まります。managedスコープは、組織がmanagedMcpServersという管理設定で配るサーバーの置き場です。Claude Codeはそこを管理設定からしか読まないため、コマンドでは書き込めません。
自分のマシンで使いたいだけなら、--scopeを外すかlocal / user / projectのどれかに替えれば通ります。組織の全員に配りたい管理者は、コマンドではなく管理設定のJSONを編集します。
エラーが出る条件とメッセージ
出るのは次のようなコマンドを実行したときです。
claude mcp add --transport http search \
--scope managed https://search.example.com/mcp画面には1行だけ表示されます。
Cannot add MCP server to scope: managed原因は--scopeの値だけです。サーバーのURLや名前、認証設定が間違っているわけではありません。add-jsonでも同じ検査が働くため、JSONを渡す形に書き換えても結果は変わりません。
スコープごとの保存先と書き込み可否
claude mcp addが扱えるのは3つのスコープです。managedはこれらと並ぶ4つ目に見えますが、性質が違います。
| スコープ | 読み込み先 | 保存先 | コマンドで書けるか |
|---|---|---|---|
| local(既定) | 読み込み先追加したプロジェクトだけ | 保存先~/.claude.json | コマンドで書けるか書ける |
| project | 読み込み先追加したプロジェクトだけ(チーム共有) | 保存先プロジェクト直下の.mcp.json | コマンドで書けるか書ける |
| user | 読み込み先自分の全プロジェクト | 保存先~/.claude.json | コマンドで書けるか書ける |
| managed | 読み込み先組織が配る全ユーザー | 保存先管理設定のmanagedMcpServers | コマンドで書けるか書けない |
--scopeを省略したときはlocalになります。「どこにも共有されず、そのプロジェクトでだけ有効」という最も狭い範囲です。
managedが書けない理由は、書き込み先がユーザーの手元のファイルではなく、管理者が配布する設定だからです。Claude Codeはこのスコープのサーバーを管理設定からだけ読むので、コマンドの書き込み先になりえません。
自分で使うサーバーを追加し直す
自分のために追加するなら、--scopeを外すのが最短です。
# 現在のプロジェクトだけで使う(--scope省略と同じ)
claude mcp add --transport http search \
https://search.example.com/mcp
# 自分の全プロジェクトで使う
claude mcp add --transport http search \
--scope user https://search.example.com/mcp
# チームで共有する(.mcp.jsonに書かれる)
claude mcp add --transport http search \
--scope project https://search.example.com/mcp選ぶ基準は次のとおりです。
- 個人の実験用や、認証情報をバージョン管理に入れたくないサーバーは
local - 複数のプロジェクトで常用する個人ツールは
user - チーム全員に同じサーバーを持たせたいなら
project
--scopeは-sと短く書けます。--transportと--headerにも-tと-Hの短縮形があります。add-jsonで複数の項目をJSONのまま登録する場合も、--scopeの指定先は同じ3つです。
projectは.mcp.jsonを生成するため、リポジトリにコミットすれば全員に届きます。なお、.mcp.jsonに書いたサーバーは、対話セッションでは初回に承認を求められます。スコープごとの詳しい挙動と認証はClaude Code MCP設定ガイドにまとめています。
組織全員に配りたい管理者は管理設定に書く
エラーの目的が「全ユーザーにこのサーバーを配る」だった場合、コマンドは使いません。管理設定のmanagedMcpServersに書きます。置き場所は、サーバー管理設定、Claude appsゲートウェイのポリシー、MDMプロファイルやレジストリポリシー、managed-settings.jsonのいずれかです。Claude Code v2.1.259以降が必要で、それより古いクライアントはこのキーを無視します。
値はサーバー名をキーにしたオブジェクトで、各エントリの形はプロジェクトの.mcp.jsonにあるHTTP / SSEサーバーと同じです。次は例示用の形です。
{
"managedMcpServers": {
"search": {
"type": "http",
"url": "https://search.example.com/mcp"
}
}
}エントリには検査があり、通らなかったものは読み込まれずに/statusへ通知が残ります。他のエントリは読み込まれます。
| 条件 | 内容 |
|---|---|
type | 内容httpかsse(streamable-httpはhttpの別名) |
url | 内容https://のURL。localhost向けでもhttp://は不可 |
| 実行系メンバー | 内容command / args / env / headersHelperを持たない |
| 変数参照 | 内容${VAR}を含めない(展開されない) |
| サーバー名 | 内容英数字・ハイフン・アンダースコアのみ |
ローカルで起動するstdioサーバーは、この仕組みでは配れません。管理設定の文書が、ユーザーのマシンで動かすプログラムを指名しないようにするためです。
headersに書いた値は、管理設定を読めるユーザー自身にも読めます。全員向けに発行した資格情報だけを入れるか、headersを省いて各ユーザーにOAuthでサインインさせる形になります。
配られたサーバーはユーザーから見てどう動くか
管理設定で配ったサーバーには、次の性質があります。
- 同じ名前のlocal / project / userのサーバーより優先される
- ユーザーは編集も削除もできず、
claude mcp removeは「組織が提供しているサーバー」と報告する - ユーザーが同じ名前で追加したものは保存はされるが、配布側が存在する間は使われない
/mcpではManaged MCPsの欄に出て、本人が自分のために無効化することはできるclaude mcp getと/mcpは、URLをホスト名までしか表示しない
managed-mcp.jsonと併用した場合は、両方のサーバーが読み込まれ、同名のときはファイル側が勝ちます。許可リスト(allowedMcpServers)の対象にはならず、拒否リスト(deniedMcpServers)は配布分にも効きます。許可・拒否リストの評価順序はManaged MCPで許可リスト・拒否リストを組織管理するで扱っています。
管理設定以外に書いたmanagedMcpServersは読まれない
managedMcpServersは管理設定の層でだけ読まれます。ユーザー設定、プロジェクト設定、ローカル設定に同じキーを書くと、Claude Codeは警告を出してキーを捨てます。ユーザーの書き込み可能なレジストリ領域(HKCU)や、埋め込み元のホストが渡す親設定からも読みません。
Claude Desktopアプリの、サードパーティ環境のCodeタブとCoworkセッションでも読まれません。これらはClaude Desktop側がMCPサーバーを供給して固定するためです。/statusとclaude doctorが、管理設定にキーがあるのに効かない旨を表示します。
Claude Desktopにも同名の管理設定がありますが、値は配列で、エントリの形も別物です。Claude Code向けの定義をそのままコピーしないでください。Claude Codeは配列形を受け付けず、読み込まずに通知を残します。
追加後に確かめる方法と、同名サーバーの優先順位
スコープを替えて追加し直したら、登録できたかをclaude mcp listで確かめます。1台のサーバーを個別に見るならclaude mcp get <名前>です。同じ名前を複数のスコープに別のエンドポイントで定義していると、claude mcp listと/mcpが競合の警告を出します。
同名のサーバーが複数の場所にあるときは、最も優先順位の高い定義が1つだけ使われ、エントリはフィールド単位では混ぜられません。優先順位は次のとおりです。
- 組織が
managedMcpServersで配ったサーバー - local
- project
- user
- プラグインが提供するサーバー
- claude.aiのコネクタ
managedスコープのサーバーは、他のどれと重なっても組織の定義が採用されます。「自分でlocalに同名で追加したのに、組織のサーバーが動き続ける」という状況はここから起きます。重複の判定は、local / project / userでは名前で、プラグインとコネクタではエンドポイントで行われます。
不要になった定義はclaude mcp remove <名前> --scope <スコープ>で消せます。OAuthのサインインはエンドポイント単位で保存されるため、プロジェクトによって読み込まれる定義が違うと、サインインもそれぞれ必要になります。
管理設定を更新したときの反映タイミング
管理者側の話をもう少し補います。managedMcpServersをサーバー管理設定で配っている場合、反映の順序はキャッシュの有無で変わります。
- キャッシュ済みの端末では、サーバーによる確認が済むまでキャッシュ分のキーを使わず、確認を待ってからMCPサーバーを読み込みます。確認に失敗したセッションは、配布サーバーなしで続き、
/statusが保留中であることを示します - 初回起動でキャッシュがない端末では、設定が届いた時点で対話セッションが接続します。すでに始まっている
claude -pの実行は、配布サーバーなしで終わることがあります
Claude appsゲートウェイでサインインする構成では、セッション開始前にポリシーが読み込まれるため、どちらの遅延も起きません。
動いている対話セッションには編集がそのまま反映されます。
- サーバーを追加すると、再起動なしで接続される
- エントリを変更すると、新しい定義で再接続される
- サーバーを削除すると、設定を読み直した時点で切断される(非対話の
-p実行は終了まで維持)
管理設定の取得元が複数ある環境では、managedSourcesBehaviorを"merge"にすると全ソースのサーバーが配られます。同名のときは優先度の高いソースのエントリがそのまま採用されます。ゲートウェイのポリシーでは、.mcp.jsonの綴りであるmcpServersをcliブロックに書くと起動時に拒否され、エラーがmanagedMcpServersを使うよう案内します。ゲートウェイは各エントリを、クライアントと同じ検査で起動時に確かめます。
似たエラーとの切り分け
claude mcp addが管理設定に起因して失敗する例は、もう1つあります。
| 画面のメッセージ | 原因 | 対処 |
|---|---|---|
Cannot add MCP server to scope: managed | 原因--scope managedを指定した | 対処local / user / projectに替える |
Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide... | 原因管理設定のstrictPluginOnlyCustomizationがtrue、またはmcpを含むリスト | 対処プラグインで配るか、管理者にHTTP / SSEならmanagedMcpServersでの配布を頼む |
後者はスコープの指定とは無関係で、--scopeを替えても直りません。この設定下では、Claude Codeは~/.claude.jsonと.mcp.jsonのMCPサーバーを読み込まないため、書いても使われないコマンドが終了コード1で止まります。v2.1.284より前は、保存して成功と表示したうえでサーバーが読み込まれませんでした。設定の仕組みはstrictPluginOnlyCustomizationの解説を参照してください。
管理設定全般の層構造はClaude Codeの管理設定ガイドにあります。
よくある質問
--scope managedを使わずに、自分のマシンだけにmanagedと同じ強制をかけられますか
コマンドでは作れません。managedスコープは管理設定からだけ読まれるため、claude mcp addで書ける範囲はlocal / user / projectの3つです。
managedMcpServersにstdioのサーバーは書けますか
書けません。command・args・env・headersHelperのいずれかを含むエントリは検査で落ち、読み込まれません。配れるのはHTTPとSSEのリモートサーバーだけです。stdioを組織で配りたい場合は、プラグインでの配布が選択肢になります。
projectスコープで追加したのに、自動化の実行で読み込まれるか心配です
対話セッションは.mcp.jsonのサーバーを使う前に承認を求めますが、claude -pの実行、Agent SDKのセッション、クラウドセッションでは、確認画面を出せないため承認なしで読み込みます。読み込ませたくないサーバーはdisabledMcpjsonServersに入れると、すべての権限モードでブロックされます。claude mcp reset-project-choicesは、対話での承認結果をリセットするコマンドです。