Connect Claude Code to tools via MCP

概要

Model Context Protocol（MCP）で外部ツール・データソースへ接続する仕組み。MCP サーバーは Claude Code にツール、データベース、API へのアクセスを与える。

仕様

トランスポートと追加方法

• JSON 設定（.mcp.json、~/.claude.json、claude mcp add-json）では type が http のエイリアスとして streamable-http を受け付ける
• url があって type が無い JSON エントリは設定エラー。Claude Code は type の無いエントリを stdio サーバーと読むため、そのサーバーをスキップして MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry を報告する
• stdio サーバーでは --（ダブルダッシュ）が Claude 自身のオプションとサーバーを起動するコマンドを分ける。-- 以降はそのままサーバーに渡される
• --env は複数の KEY=value を受け付ける。サーバー名が --env の直後に来ると別のペアとして読まれ拒否されるため、--env とサーバー名の間に別のオプションを 1 つ以上置く
• type: "ws" は http と同じ url、headers、headersHelper、timeout、alwaysLoad を受け付ける。認証はヘッダーのみ
• stdio サーバーの環境には CLAUDE_PROJECT_DIR がプロジェクトルートとして設定される。これは安定したプロジェクトルートで、セッション中に作業ディレクトリを追加・削除しても変わらない
  • 自身のファイルシステムアクセスを許可ディレクトリ集合に限りたいサーバーは MCP の roots/list リクエストを実装する。Claude Code はセッションの起動ディレクトリと、--add-dir / /add-dir / additionalDirectories で与えたすべての追加作業ディレクトリを返し、その集合が変わると notifications/roots/list_changed を送る（v2.1.203 以降）
  • この変数はサーバーの環境に設定されるものでありClaude Code 自身の環境ではない。project スコープの .mcp.json や user / local スコープのサーバーエントリの command / args で ${VAR} 展開して参照するには ${CLAUDE_PROJECT_DIR:-.} のような既定値が必要。plugin が提供する MCP 設定は ${CLAUDE_PROJECT_DIR} を直接置換するので既定値は不要

管理コマンド

claude mcp list        # 設定済みサーバーを一覧
claude mcp get notion  # 特定サーバーの詳細
claude mcp remove notion
claude mcp add-json <name> '<json>'
claude mcp add-from-claude-desktop
claude mcp reset-project-choices
claude mcp serve       # Claude Code 自身を stdio MCP サーバーとして起動
/mcp                   # セッション内でサーバー状態を確認

• claude mcp add は成功時に Added ... を出力する。これは設定が書かれたことを意味する
• claude mcp list は各サーバーの健全性（✔ Connected / ! Needs authentication / ✘ Failed to connect）を表示する
• 承認待ちの project スコープサーバーは ⏸ Pending approval (run `claude` to approve) と表示される。拒否されたサーバーは claude mcp get <name> で ✘ Rejected (see disabledMcpjsonServers in settings)
• WebSocket サーバーは claude mcp list に現れない。claude mcp get <name> か /mcp パネルで確認する
• claude mcp serve は起動時に何も出力しない。stdio MCP サーバーは stdin / stdout で通信するため、無言でブロックしたターミナルはサーバーが動作中であることを意味する
• claude mcp コマンドで追加するサーバー名に使えるのは英数字・ハイフン・アンダースコアのみ

サーバー状態の詳細:

• 以前使ったリモート（HTTP / SSE）サーバーは cached 2h ago · connects on first use · 5 tools のような cached 状態を示すことがある。前セッションからツール一覧を読み込んでおり、Claude が最初にツールを呼んだときに接続する。すべてのサーバーを起動時に接続させるには MCP_DISCOVERY_CACHE=0。v2.1.221 以降が必要
• ✘ Failed to connect のとき、claude mcp list は状態行に失敗詳細（HTTP ステータスやエラーコード、サーバーが返したエラーテキスト）を付け、claude mcp get <name> は Issue: 行に表示する。認証情報らしきテキストは伏せられ、秘密を含みうる展開後のサーバー URL は決して含まれない。✘ Connection error には詳細を付けない（v2.1.219 以降）
• url が空のリモートサーバーは not configured と表示され、接続を試みない
• 設定値の先頭・末尾に隠れた空白があると警告する。command、url、各 args、env と headers の値とキー名を検査し、値を出力せずに Leading or trailing whitespace in: headers.Authorization のように該当フィールドを示す。空白は自動で除去されない
• 予約サーバー名: workspace、claude-in-chrome、computer-use、Claude Preview、Claude Browser。予約名のサーバーは読み込み時にスキップされ改名を促す警告が出る。claude mcp add は予約名をエラーで拒否する

インストールスコープ

• -s / --scope で指定する（local / project / user）
• local スコープは ~/.claude.json のそのプロジェクトのパスの下に保存される。MCP の「local スコープ」は一般の local settings（.claude/settings.local.json）とは別物
• project スコープのサーバーは、対話セッションでは使用前に承認を求められる。承認の選択をリセットするには claude mcp reset-project-choices
• claude -p 実行、Agent SDK セッション、cloud セッションはそのプロンプトを出せないため、project スコープのサーバーを確認なしに読み込む。除外するには disabledMcpjsonServers に追加するか、--setting-sources / SDK の settingSources で project settings ごと除外する

優先順位（同じサーバーが複数箇所で定義されている場合、最も優先度の高いソースの定義でただ 1 回だけ接続する。フィールドはスコープをまたいでマージされない）:

1. Local scope
2. Project scope
3. User scope
4. Plugin が提供するサーバー
5. claude.ai connector

• 3 つのスコープは名前で重複を判定する。plugin と connector はエンドポイント（URL / コマンド）で判定する

.mcp.json の環境変数展開

• ${VAR}: 環境変数 VAR の値に展開する
• ${VAR:-default}: VAR が設定されていればその値、無ければ default
• 展開できる場所: command、args、env、url（HTTP 系）、headers（HTTP 認証）
• 参照する環境変数が未設定で既定値も無い場合、設定は読み込まれる。claude mcp list にそのサーバーの missing-variable 警告が出て、${VAR} のテキストがそのまま使われる

project サーバーの承認と workspace trust

• v2.1.196 以降、claude mcp list と claude mcp get は、そのフォルダで claude を実行して workspace trust ダイアログを承認するまで、リポジトリにチェックインされていない settings ファイルからのみ .mcp.json の承認を読む
• クローンしたリポジトリは自身のサーバーを承認できない。project の .claude/settings.json にコミットされた enableAllProjectMcpServers / enabledMcpjsonServers は untrusted なフォルダでは無視され、サーバーは ⏸ Pending approval のままになる
• untrusted なフォルダでも有効な承認元: user の ~/.claude/settings.json、managed settings、--settings で渡した settings
• 追跡されていない .claude/settings.local.json の承認も有効になるが、そのフォルダかその親の trust ダイアログを承認した後のみ（例外は自分の設定ホーム）
• どの settings ファイルの disabledMcpjsonServers エントリも引き続きサーバーを拒否する

サーバーの無効化（設定を残したまま）

/mcp パネルでトグルすると、プロジェクトごとの選択が ~/.claude.json の 2 つのリストのいずれかに記録される。

• disabledMcpServers: 既定でオンのサーバー（user 設定のサーバー、plugin サーバー、claude.ai connector、組み込みサーバー）の opt-out リスト。claude.ai connector を無効化すると表示名（例: claude.ai Slack）で書かれる

• enabledMcpServers: 既定でオフの組み込みサーバー（computer-use など）の opt-in リスト

• 各サーバーについて Claude Code はどちらか一方のリストのみを参照するため、相互に上書きしない。通常のサーバーを enabledMcpServers に、既定オフの組み込みサーバーを disabledMcpServers に書いても無視される

• これらは .mcp.json のサーバー承認を制御する enabledMcpjsonServers / disabledMcpjsonServers とは無関係

動的更新と再接続

• MCP の list_changed 通知をサポートし、サーバーがツール・prompt・リソースを動的に更新できる。通知を受けると自動で再取得する
• 再取得に失敗した場合、後の再取得が成功するまで以前に発見したものを保持する（v2.1.214 以降。それ以前は一時的なエラーで空リストに置き換わっていた）
• HTTP / SSE サーバーがセッション中に切断すると指数バックオフで自動再接続する。最大 5 回、初回 1 秒から倍々。5 回失敗するとサーバーは failed になり /mcp から手動で再試行できる。stdio サーバーはローカルプロセスであり自動再接続しない
• 起動時の初回接続失敗にも同じバックオフが適用される。5xx・接続拒否・タイムアウトのような一時的エラーは最大 3 回再試行し、なお接続できなければ failed になる。認証エラーと not-found は設定変更が必要なため再試行しない
• 接続に失敗したサーバーがあると、Claude Code は Claude にどのサーバーが失敗したかと接続エラーを伝える（tool search が必要。既定で有効）
• v2.1.191 以降、接続成功後の capability discovery（tools/list、prompts/list、resources/list）も一時的なネットワーク・サーバーエラーを短いバックオフで最大 3 回再試行する。認証エラー、4xx、リクエストタイムアウトは再試行しない

タイムアウトと出力上限

• 起動タイムアウトは MCP_TIMEOUT 環境変数（例: MCP_TIMEOUT=10000 で 10 秒）
• サーバーごとのツール実行タイムアウトは .mcp.json エントリの timeout フィールド（ミリ秒。例: "timeout": 600000）。そのサーバーについて MCP_TOOL_TIMEOUT 環境変数を上書きする
• サーバーごとの timeout はツール呼び出しごとの hard な実時間上限で、サーバーからの progress 通知では延長されない。1000 未満の値は無視され MCP_TOOL_TIMEOUT（未設定時は約 28 時間）へフォールバックする
• HTTP / SSE / claude.ai connector には、サーバーの最初の応答バイトまでをカバーする 2 つ目の per-request タイマーがある。既定 60 秒。サーバーごとの timeout または MCP_TOOL_TIMEOUT を 60 秒以上にするとその値まで上がるが、それより低い値では短くならない。未設定の MCP_TOOL_TIMEOUT の 28 時間の既定はこれに影響しない。stdio と WebSocket には per-request タイマーが無い
• idle timeout: 応答も progress 通知も無いまま idle window を過ぎたツール呼び出しは、実時間上限を待たずエラーで中断する。v2.1.187 以降。IDE サーバーと SDK in-process サーバーを除く全種別に適用される。既定は HTTP / SSE / WebSocket / claude.ai connector が 5 分、stdio が 30 分。CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT（ミリ秒）で変更、0 で無効化する
• 1000 以上のサーバーごとの timeout は idle timeout の下限としても働く（v2.1.203 以降）
• MCP ツール出力が 10,000 トークンを超えると警告が出る。既定の上限は 25,000 トークンで MAX_MCP_OUTPUT_TOKENS で変更する（警告の閾値は固定）
• 環境変数は自前の上限を宣言していないツールに適用される。_meta["anthropic/maxResultSizeChars"] を設定したツールはテキストコンテンツについてその値を使う。画像データを返すツールは引き続き MAX_MCP_OUTPUT_TOKENS の対象
• サーバー作者は tools/list 応答の _meta["anthropic/maxResultSizeChars"] で個別ツールの上限を上げられる。ハード上限は 500,000 文字。注釈が無い場合、既定閾値を超える結果はディスクへ永続化され会話ではファイル参照に置き換えられる

長いツール呼び出しの自動バックグラウンド化

• メイン会話の MCP ツール呼び出しが 2 分を超えて実行中なら、セッションをブロックせずバックグラウンドタスクへ移る。Claude は即座にタスク ID を受け取り、結果は完了時にタスク通知として届く。v2.1.212 以降が必要
• タスクは /tasks に現れ、そこで停止もできる。セッション終了後は残らない
• バックグラウンドで動いている間も per-call の上限（timeout / MCP_TOOL_TIMEOUT の実時間上限、CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT の idle timeout）は適用される
• 閾値は CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS（ミリ秒）で変更、0 で無効化する。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 でも無効になる
• バックグラウンド化されないもの: subagent からの呼び出し、IDE サーバーへの呼び出し、非対話モードでの呼び出し（CLAUDE_AUTO_BACKGROUND_TASKS=1 の場合を除く）、elicitation ダイアログを開いて待っている呼び出し

plugin が提供する MCP サーバー

• plugin ルートの .mcp.json、または plugin.json のインライン定義で MCP サーバーを定義する
• plugin を有効にすると Claude Code が自動でサーバーを起動する。追加・削除は plugin のインストール／アンインストールで行い、/mcp コマンドでは行わない。ただし /mcp でトグルオフはできる
• セッション中に plugin を有効・無効にした場合、MCP サーバーを接続・切断するには /reload-plugins を実行する。リロード時、設定が変わっていない plugin サーバーのライブ接続は保たれる
• パスのプレースホルダ: ${CLAUDE_PLUGIN_ROOT} は plugin のインストールディレクトリ、${CLAUDE_PLUGIN_DATA} は永続状態ディレクトリ、${CLAUDE_PROJECT_DIR} は安定したプロジェクトルートに解決される。置換対象は stdio の command / args / env、http / sse / ws の url / headers / headersHelper
• plugin バンドルの MCP サーバーのツール名は mcp__plugin_<plugin-name>_<server-name>__<tool-name>。A-Z、a-z、0-9、_、- 以外の文字は _ に置き換えられる。permission ルール、skill の allowed-tools、subagent の tools、hook matcher ではこのフルネームを使う。素のサーバーキー（mcp__database-tools__.*）を書いた hook matcher は plugin バンドルのサーバーでは発火しない
• サーバー自体は plugin:<plugin-name>:<server-name> というスコープ名で登録される。mcp_tool hook の server フィールドなど、設定済みサーバー名を期待する場所ではこの名前を使う

認証

• リモートサーバーが 401 Unauthorized または 403 Forbidden を返すと、認証が必要とマークされる
• サインイン済みの OAuth サーバーへのリクエストが 401 を返した場合、保存トークンを更新して再接続し 1 回だけ再試行する。その再試行も失敗したときにのみ /mcp でフラグを立てる（v2.1.206 以降）
• v2.1.195 以降、サーバーが保存済み refresh token を拒否したためにトークン更新が失敗した場合、/mcp を指す通知を即座に表示する。サーバーのメニューに Re-authenticate がある
• 認証が必要なサーバーがあると起動時に通知が出る（v2.1.193 以降）
• 非対話モードには /mcp パネルが無いため OAuth フローを実行できない。v2.1.196 以降、tool search 有効時は、認証が必要なサーバーのツールが使えないことを Claude に伝える
• headers.Authorization を設定していてサーバーがそのヘッダーを拒否した場合、OAuth にフォールバックせず接続失敗として報告する
• claude mcp login <name> でシェルから OAuth フローを実行する（v2.1.186 以降）。claude mcp logout <name> で保存済み認証情報を消す
• v2.1.191 以降、ローカルブラウザが使えない状況（SSH、ディスプレイサーバーの無い Linux）を検出して認可 URL を出力する。ローカルで開き、ブラウザのアドレスバーのリダイレクト URL 全体をプロンプトへ貼り戻す。貼り付けには対話ターミナルが必要（ssh -t）。--no-browser で強制できる
• --callback-port で OAuth コールバックのポートを固定する（http://localhost:PORT/callback 形式の事前登録リダイレクト URI に合わせる）。単独でも --client-id と併用でも使える
• Dynamic Client Registration に対応しないサーバーには事前設定の認証情報を使う。--client-id でクライアント ID、--client-secret はマスク入力で secret を尋ねる。MCP_CLIENT_SECRET 環境変数で対話プロンプトを飛ばせる。client secret は macOS のシステムキーチェーン、または credentials ファイルに安全に保存され、設定ファイルには入らない
• これらのフラグは HTTP と SSE にのみ適用され、stdio には効果が無い
• oauth.authServerMetadataUrl で OAuth メタデータ探索を上書きする。既定は RFC 9728 の /.well-known/oauth-protected-resource、次に RFC 8414 の /.well-known/oauth-authorization-server。URL は https:// でなければならない。メタデータの scopes_supported が上流サーバーの広告するスコープを上書きする
• oauth.scopes で認可フロー時に要求するスコープを固定する。値は RFC 6749 §3.3 の scope パラメータ形式に合わせたスペース区切りの 1 文字列。authServerMetadataUrl と /.well-known で発見したスコープの両方より優先される
  • v2.1.196 以降、oauth.scopes 未設定時はサーバーの WWW-Authenticate ヘッダーまたは protected resource metadata が提供するスコープを要求し、どちらも無ければ scope パラメータを送らない
  • 認可サーバーが scopes_supported に offline_access を広告している場合、固定したスコープに追加してトークンをブラウザ再サインインなしに更新できるようにする
  • ツール呼び出しで 403 insufficient_scope が返ると、同じ固定スコープで再認証する

headersHelper

• OAuth 以外の認証方式（Kerberos、短命トークン、内部 SSO）向けに、接続時にリクエストヘッダーを生成するコマンド
• コマンドは文字列のキーと値の JSON オブジェクトを stdout に書く
• シェルで、10 秒のタイムアウト付き、セッションの現在の作業ディレクトリから実行される。スクリプトには絶対パスか PATH 上のコマンドを使う
• 動的ヘッダーは同名の静的 headers を上書きする
• 接続のたび（セッション開始時と再接続時）に新しく実行される。キャッシュは無い
• v2.1.193 以降、ツール呼び出しが 401 / 403 を返すと自動でヘルパーを再実行し、新しいヘッダーで再接続して 1 回だけ再試行する

ヘルパー実行時に設定される環境変数:

• plugin 提供のサーバーでは作業ディレクトリが plugin ルートに設定されるため、相対 headersHelper パスは plugin ディレクトリ内で解決される（v2.1.195 以降）
• plugin 提供の headersHelper は plugin の ${user_config.*} 値を参照できない（シェル経由で実行されるため）。代わりにサーバーの headers フィールドに ${user_config.KEY} を置く
• headersHelper は任意のシェルコマンドを実行する。project / local スコープで定義した場合、workspace trust ダイアログを承認した後にのみ実行される

claude.ai connector

• claude.ai アカウントでログインしていると、claude.ai で追加した MCP サーバー（connector）が自動で使える
• claude.ai の設定でサーバーを追加する。Team と Enterprise プランでは管理者のみが追加できる
• /mcp に claude.ai 由来であることを示す表示付きで並ぶ
• v2.1.161 以降、一度もサインインしていない connector は claude.ai セクション末尾の Show unused connectors 行に畳まれる
• connector が取得されるのは、有効な認証方式が claude.ai サブスクリプションログインのときのみ。ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / apiKeyHelper が有効な場合、Amazon Bedrock などの第三者プロバイダが有効な場合、CLAUDE_CODE_OAUTH_TOKEN が claude setup-token のトークンを保持している場合は読み込まれない
• connected · session token rejected は、Claude Code のログイン由来のトークンを claude.ai が拒否した状態（多くはログイン期限切れ）。connector を再認可しても解決しない。/login でサインインし直し、/mcp から connector を再接続する
• Claude Code で追加したサーバーは、同じ URL を指す claude.ai connector より優先される。この場合 /mcp は connector を hidden として一覧し、connector を使いたい場合の重複解消方法を示す
• Microsoft 365、Gmail、Google Calendar など一部の Anthropic ホスト connector は、上流 ID プロバイダが claude.ai の登録したリダイレクト URL しか受け付けないため Claude Code からのローカル OAuth に対応しない。v2.1.162 以降、/mcp で認証しようとすると claude.ai の Settings → Connectors で接続するよう案内される

組織による connector ツールの制御:

• ask に設定されたツール: 呼び出しのたびに Your organization requires approval for this tool の理由でプロンプトを出す。acceptEdits / auto / bypassPermissions モードでも出て、選択を記憶する選択肢は出ない。一致する allow ルールでもプロンプトは省けない。dontAsk モードでは拒否される
• blocked に設定されたツール: Claude が見る前に除外され、ツール一覧に現れない

connector の無効化:

• disableClaudeAiConnectors を任意の settings スコープで true にする。any-source-true のセマンティクスで、どこかのソースの true が優先される。project レベルの false は user / policy レベルの true を打ち消せない。--mcp-config で明示的に渡したサーバーは影響を受けない
• ENABLE_CLAUDEAI_MCP_SERVERS=false でも同じ効果（そのシェルセッション限り）
• 個別にブロックするには deniedMcpServers に名前または URL パターンで追加する（例: serverName に "claude.ai Slack"）
• 現在のプロジェクトだけ切り替えるには /mcp パネルを使う

ツール入力スキーマのルートレベル combinator

• Claude API はスキーマルートの anyOf / oneOf / allOf を受け付けない。properties 内にネストした combinator は受け付け、Claude Code はそのまま送る
• v2.1.195 以降、ルートレベル combinator を持つツールも利用可能なまま。API へ送る前にスキーマを単一オブジェクトへ平坦化し、どのパラメータ群が組になるかを示す文をツールの description の先頭に付ける
  • allOf: 全ブランチの properties をマージし、各ブランチの required はそのまま適用される
  • anyOf / oneOf: 全ブランチの properties をマージし、各ブランチの required はスキーマで強制せず description に記述する
• 受け入れ可能なスキーマを作れない場合や、この書き換えを有効にするリモート設定を受け取らないデプロイでは、そのツール 1 つをスキップし理由をサーバーのログに記録して、他のツールは残す

承認の強制（requiresUserInteraction）

• サーバー作者は tools/list 応答の _meta["anthropic/requiresUserInteraction"] を true（JSON boolean のみ）にすると、そのツールの呼び出しごとに明示的な承認を求められる
• acceptEdits / auto / bypassPermissions モードでもプロンプトが出て、「don't ask again」は提示されない。一致する allow ルールでも省けない。dontAsk モードでは拒否される
• 非対話モードで --permission-prompt-tool を使う場合、フラグ付きツールへの allow 結果は MCP tool requires user interaction; not supported via --permission-prompt-tool として deny に変換される。Agent SDK の canUseTool コールバックはこれらの呼び出しを受け取り承認できる
• v2.1.199 以降が必要。それ以前は無視され通常の permission フローになる
• Remote Control や Agent SDK 製アプリのワンタップ承認は、この注釈が付いたツールでは提供されず、完全な permission prompt が表示される

elicitation

• MCP サーバーはタスク中に構造化された入力を求められる。設定は不要で、サーバーが要求するとダイアログが自動で表示される
• Form mode: サーバーが定義したフォームフィールドのダイアログを表示する
• URL mode: 認証や承認のためブラウザ URL を開く。ブラウザで完了してから CLI で確認する
• ダイアログを出さず自動応答するには Elicitation hook を使う

MCP リソース

• @ を入力すると接続済み MCP サーバーのリソースがファイルと並んで補完メニューに現れる
• 参照形式は @server:protocol://resource/path（例: @github:issue://123）
• 1 つのプロンプトで複数参照できる
• 参照されたリソースは自動取得され添付として含まれる

MCP prompts をコマンドとして使う

• /mcp__servername__promptname の形式でコマンド一覧に現れる
• 引数はコマンドの後にスペース区切りで渡す
• サーバー名と prompt 名は正規化され、スペースはアンダースコアに変換される

tool search

• 既定で有効。MCP ツールは upfront に読み込まれず deferred になり、Claude が必要になったときに検索ツールで見つける。セッション開始時にはツール名とサーバーの instructions だけが読み込まれる
• サーバーごとの固定のツール上限は無い。実質の上限はコンテキストウィンドウの予算
• tool_reference ブロックをサポートするモデルが必要: Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 以降

• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定すると tool search はオフのままになり、ENABLE_TOOL_SEARCH でも上書きできない。defer_loading のツール定義と tool_reference コンテンツブロックが必要とする beta ヘッダーを剥がすため
• v2.1.221 より前は、ENABLE_TOOL_SEARCH=true にしない限り Google Cloud's Agent Platform の全モデルで tool search が無効だった
• permissions.deny に ToolSearch を追加して ToolSearch ツール自体を無効にすることもできる
• サーバー作者向け: server instructions が Claude にツールを検索すべき場面を伝える。ツールの description と server instructions はそれぞれ 2KB で切り詰められる

deferral からの除外:

• サーバー設定に alwaysLoad: true を設定すると、ENABLE_TOOL_SEARCH に関わらずそのサーバーの全ツールがセッション開始時にコンテキストへ読み込まれる。全サーバー種別で使える
• サーバーは _meta に "anthropic/alwaysLoad": true を含めて個別ツールを always-loaded にできる
• alwaysLoad: true は起動時にそのサーバーのツールを待たせる（標準の 5 秒の接続タイムアウトが上限）。有効な cached エントリを持つリモートサーバーは接続せずキャッシュからツールを供給するため起動を待たせない。他のサーバーは既定でバックグラウンド接続する。MCP_CONNECTION_NONBLOCKING=0 で起動時に待たせられる

ツールが揃うまでの待機

• リクエストがまだバックグラウンドで接続中のサーバーのツールを必要とする場合、Claude はそのサーバーを待つ
• tool search 有効（既定）なら待機は ToolSearch 呼び出しの内側で起きる
• tool search 無効なら WaitForMcpServers ツールを使う。tool search が無効になる構成: カスタム ANTHROPIC_BASE_URL、ENABLE_TOOL_SEARCH=false、Google Cloud's Agent Platform で Claude 4.5 世代より前のモデル
• Azure ホストの Microsoft Foundry デプロイでは、サーバー側の拒否を API からしか検知できないため、WaitForMcpServers ではなく tool search 経路で開始する。upfront 読み込みへ切り替わった後は、接続を終えたサーバーのツールが Claude の次のリクエストで使えるようになる
• tool search 有効時、Claude の作業中にサーバーの接続が完了すると、同じターンの次のリクエストでサーバーのツール名が Claude に一覧される

設定

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server
claude mcp add-json events-server '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
claude mcp login sentry --no-browser

// .mcp.json
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

{
  "disableClaudeAiConnectors": true
}

制約・注意点

• 接続前に各サーバーを信頼できるか確認する。外部コンテンツを取得するサーバーは prompt injection のリスクをもたらしうる
• SSE トランスポートは非推奨。可能なら HTTP を使う
• Claude Desktop からのインポートは macOS と WSL でのみ動く。名前に英数字・ハイフン・アンダースコア以外の文字を含むサーバーはインポートできず、拒否した名前を報告して他はインポートする。同名のサーバーが既にある場合は数字の接尾辞が付く（server_1）
• claude mcp serve が公開するのは Claude Code のツールだけなので、個別のツール呼び出しのユーザー確認はクライアント側の責任

関連

• facts/claude-code/settings.md
• facts/claude-code/permissions.md
• facts/claude-code/plugins.md
• facts/claude-code/sub-agents.md
• facts/claude-code/env-vars.md
• facts/claude-code/cli-reference.md
• facts/claude-code/commands.md
• facts/claude-code/tools-reference.md
• facts/claude-code/security.md
• facts/claude-code/headless.md