29 MCP サーバーを検索してビルドする29 MCP サーバーを検索してビルドする

30</h2>30</h2>

31 31 

32[Anthropic Directory](https://claude.ai/directory) でレビュー済みのコネクタを参照してください。Directory コネクタは Claude Code と同じ MCP インフラストラクチャを使用しているため、`claude mcp add` を使用して、そこにリストされているリモートサーバーを追加できます。32[Anthropic Directory](https://claude.ai/directory) でレビュー済みのコネクターを参照してください。Directory コネクターは Claude Code と同じ MCP インフラストラクチャを使用しているため、`claude mcp add` を使用して、そこにリストされているリモートサーバーを追加できます。

33 33 

34<Warning>34<Warning>

35 接続する前に、各サーバーを信頼していることを確認してください。外部コンテンツを取得するサーバーは、[プロンプトインジェクションリスク](/docs/ja/security#protect-against-prompt-injection)にさらされる可能性があります。35 接続する前に、各サーバーを信頼できることを確認してください。外部コンテンツを取得するサーバーは、[プロンプトインジェクションリスク](/docs/ja/security#protect-against-prompt-injection) にあなたを晒す可能性があります。

36</Warning>36</Warning>

37 37 

38独自のサーバーをビルドするには、プロトコルの基礎については [MCP サーバーガイド](https://modelcontextprotocol.io/docs/develop/build-server) を、認証、テスト、Directory への提出については [Claude コネクタビルディングドキュメント](https://claude.com/docs/connectors/building) を参照してください。38独自のサーバーをビルドするには、プロトコルの基礎については [MCP サーバーガイド](https://modelcontextprotocol.io/docs/develop/build-server) を、認証、テスト、Directory への提出については [Claude コネクター構築ドキュメント](https://claude.com/docs/connectors/building) を参照してください。

39 39 

40公式の [`mcp-server-dev` プラグイン](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) を使用して、Claude にサーバーをスキャフォルドしてもらうこともできます。40公式の [`mcp-server-dev` プラグイン](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev) を使用して、Claude にサーバーをスキャフォールドしてもらうこともできます。

41 41 

42<Steps>42<Steps>

43 <Step title="プラグインをインストールする">43 <Step title="プラグインをインストールする">

47 /plugin install mcp-server-dev@claude-plugins-official47 /plugin install mcp-server-dev@claude-plugins-official

48 ```48 ```

49 49 

50 Claude Code がマーケットプレイスが見つからないと報告する場合は、まず `/plugin marketplace add anthropics/claude-plugins-official` を実行してから、インストールを再試行してください。インストール後、`/reload-plugins` を実行して、現在のセッションでアクティブにします。50 インストールが失敗した場合は、Claude Code が報告するメッセージに一致させてください：

51 

52 * `Marketplace "claude-plugins-official" not found`：`/plugin marketplace add anthropics/claude-plugins-official` でマーケットプレイスを追加してから、インストールを再試行してください。

53 * [プラグインがマーケットプレイスで見つかりません](/docs/ja/discover-plugins#install-plugins)：プラグイン名を確認してください。

54 

55 インストール概要が `Run /reload-plugins to activate.` を報告する場合、Claude Code はその後、そのリロードを実行します。リロードが次のメッセージが会話を再度読み込むことになると警告する場合は、`/reload-plugins --force` を実行してください。

51 </Step>56 </Step>

52 57 

53 <Step title="ビルドスキルを実行する">58 <Step title="ビルドスキルを実行する">

55 /mcp-server-dev:build-mcp-server60 /mcp-server-dev:build-mcp-server

56 ```61 ```

57 62 

58 Claude があなたのユースケースについて質問し、リモート HTTP またはローカル stdio サーバーをスキャフォルドします。63 Claude があなたのユースケースについて質問し、リモート HTTP またはローカル stdio サーバーをスキャフォールドします。

59 </Step>64 </Step>

60</Steps>65</Steps>

61 66 

63 MCP サーバーのインストール68 MCP サーバーのインストール

64</h2>69</h2>

65 70 

66MCP サーバーは、ニーズに応じて複数の方法で設定できます：71MCP サーバーは、ニーズに応じてさまざまな方法で設定できます。

67 72 

68<h3 id="option-1-add-a-remote-http-server">73<h3 id="option-1-add-a-remote-http-server">

69 オプション 1：リモート HTTP サーバーを追加する74 オプション 1: リモート HTTP サーバーを追加する

70</h3>75</h3>

71 76 

72HTTP サーバーはリモート MCP サーバーに接続するための推奨オプションです。これはクラウドベースのサービスに最も広くサポートされているトランスポートです。77HTTP サーバーは、リモート MCP サーバーに接続するための推奨オプションです。これはクラウドベースのサービスに対して最も広くサポートされているトランスポートです。

73 78 

74```bash theme={null}79```bash theme={null}

75# 基本的な構文80# 基本的な構文

76claude mcp add --transport http <name> <url>81claude mcp add --transport http <name> <url>

77 82 

78# 実際の例：Notion に接続する83# 実際の例: Notion に接続

79claude mcp add --transport http notion https://mcp.notion.com/mcp84claude mcp add --transport http notion https://mcp.notion.com/mcp

80 85 

81# Bearer トークンを使用した例86# Bearer トークン付きの例

82claude mcp add --transport http secure-api https://api.example.com/mcp \87claude mcp add --transport http secure-api https://api.example.com/mcp \

83 --header "Authorization: Bearer your-token"88 --header "Authorization: Bearer your-token"

84```89```

85 90 

86MCP サーバーを `.mcp.json`、`~/.claude.json`、または `claude mcp add-json` で JSON を使用して設定する場合、`type` フィールドは `http` のエイリアスとして `streamable-http` を受け入れます。MCP 仕様ではこのトランスポートに `streamable-http` という名前を使用しているため、サーバードキュメントからコピーされた設定は変更なしで機能します。91`.mcp.json`、`~/.claude.json`、または `claude mcp add-json` で JSON を使用して MCP サーバーを設定する場合、`type` フィールドは `http` のエイリアスとして `streamable-http` を受け入れます。MCP 仕様ではこのトランスポートに `streamable-http` という名前を使用しているため、サーバードキュメントからコピーされた設定は変更なしで機能します。

92 

93`url` を持つが `type` を持たない JSON エントリは設定エラーです。Claude Code は `type` を持たないエントリを stdio サーバーとして読み込むためです。Claude Code はそのサーバーをスキップし、`MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry` と報告します。v2.1.202 より前では、Claude Code はこの設定ミスを `command: expected string, received undefined` と報告していました。

87 94 

88`url` を持つが `type` を持たない JSON エントリは設定エラーです。Claude Code は `type` を持たないエントリを stdio サーバーとして読み取るためです。Claude Code はそのサーバーをスキップし、`MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry` と報告します。v2.1.202 より前は、Claude Code はこの設定ミスを `command: expected string, received undefined` と報告していました。95`--output-format stream-json` 実行では、Claude Code はスキップされた `--mcp-config` エントリを `system/init` イベントの [`mcp_server_errors` フィールド](/docs/ja/headless#stream-responses) でも報告するため、スクリプトはサーバーが読み込まれなかったことを検出できます。これには Claude Code v2.1.219 以降が必要です。

89 96 

90<h3 id="option-2-add-a-remote-sse-server">97<h3 id="option-2-add-a-remote-sse-server">

91 オプション 2：リモート SSE サーバーを追加する98 オプション 2: リモート SSE サーバーを追加する

92</h3>99</h3>

93 100 

94<Warning>101<Warning>

95 SSE（Server-Sent Events）トランスポートは非推奨です。利用可能な場合は HTTP サーバーを使用してください。102 SSE（Server-Sent Events）トランスポートは非推奨です。利用可能な場合は HTTP サーバーを使用してください。

96</Warning>103</Warning>

97 104 

105一部のサービスは SSE エンドポイントのみを公開しています。これらを [HTTP サーバー](#option-1-add-a-remote-http-server) と同じ `claude mcp add --transport http <name> <url>` コマンドで追加してください。Claude Code は最初に HTTP トランスポートを試し、サーバーがそれを受け入れない場合は SSE に切り替わります。自動切り替えには Claude Code v2.1.265 以降が必要です。

106 

107以前のバージョンで、または SSE 経由で直接接続するには、代わりに `--transport sse` を渡してください。

108 

98```bash theme={null}109```bash theme={null}

99# 基本的な構文110# 基本的な構文

100claude mcp add --transport sse <name> <url>111claude mcp add --transport sse <name> <url>

101 112 

102# 実際の例：Asana に接続する113# 実際の例: Asana に接続

103claude mcp add --transport sse asana https://mcp.asana.com/sse114claude mcp add --transport sse asana https://mcp.asana.com/sse

104 115 

105# 認証ヘッダーを使用した例116# 認証ヘッダー付きの例

106claude mcp add --transport sse private-api https://api.company.com/sse \117claude mcp add --transport sse private-api https://api.company.com/sse \

107 --header "X-API-Key: your-key-here"118 --header "X-API-Key: your-key-here"

108```119```

109 120 

110<h3 id="option-3-add-a-local-stdio-server">121<h3 id="option-3-add-a-local-stdio-server">

111 オプション 3：ローカル stdio サーバーを追加する122 オプション 3: ローカル stdio サーバーを追加する

112</h3>123</h3>

113 124 

114Stdio サーバーはマシン上でローカルプロセスとして実行されます。システムへの直接アクセスやカスタムスクリプトが必要なツールに最適です。125Stdio サーバーはマシン上のローカルプロセスとして実行されます。システムへの直接アクセスやカスタムスクリプトが必要なツールに最適です。

115 126 

116Claude Code は、生成されたサーバーの環境に `CLAUDE_PROJECT_DIR` を設定して、プロジェクトルートを指定するため、サーバーは作業ディレクトリに依存することなくプロジェクト相対パスを解決できます。これは hooks が `CLAUDE_PROJECT_DIR` 変数で受け取るのと同じディレクトリです。サーバープロセス内から読み取ります。例えば、Node では `process.env.CLAUDE_PROJECT_DIR`、Python では `os.environ["CLAUDE_PROJECT_DIR"]` です。127Claude Code は、生成されたサーバーの環境に `CLAUDE_PROJECT_DIR` を設定して、プロジェクトルートに設定します。これにより、サーバーは作業ディレクトリに依存することなくプロジェクト相対パスを解決できます。これは hooks が `CLAUDE_PROJECT_DIR` 変数で受け取るのと同じディレクトリです。サーバープロセス内からこれを読み取ります。例えば、Node では `process.env.CLAUDE_PROJECT_DIR`、Python では `os.environ["CLAUDE_PROJECT_DIR"]` です。

117 128 

118`CLAUDE_PROJECT_DIR` は安定したプロジェクトルートであり、セッション中に作業ディレクトリを追加または削除しても変わりません。ファイルシステムアクセスを許可されたディレクトリのセットに制限するサーバーは、代わりに MCP `roots/list` リクエストを実装する必要があります。Claude Code は `roots/list` に、セッションの起動ディレクトリと、`--add-dir`、`/add-dir`、または `additionalDirectories` 設定で付与した [追加の作業ディレクトリ](/docs/ja/permissions#working-directories) をすべて返します。Claude Code は、そのセットが変わるときに `notifications/roots/list_changed` を送信します。v2.1.203 より前は、`roots/list` は起動ディレクトリのみを返し、Claude Code は `notifications/roots/list_changed` を送信していませんでした。129`CLAUDE_PROJECT_DIR` は安定したプロジェクトルートであり、セッション中に作業ディレクトリを追加または削除しても変わりません。ファイルシステムアクセスを許可されたディレクトリのセットに制限するサーバーは、代わりに MCP `roots/list` リクエストを実装する必要があります。Claude Code は `roots/list` にセッションの起動ディレクトリと、`--add-dir`、`/add-dir`、または `additionalDirectories` 設定で付与した [追加作業ディレクトリ](/docs/ja/permissions#working-directories) をすべて返します。Claude Code はそのセットが変わるときに `notifications/roots/list_changed` を送信します。v2.1.203 より前では、`roots/list` は起動ディレクトリのみを返し、Claude Code は `notifications/roots/list_changed` を送信していませんでした。

119 130 

120この変数はサーバーの環境に設定され、Claude Code 自体の環境には設定されないため、プロジェクトスコープまたはユーザースコープの `.mcp.json` `command` または `args` で `${VAR}` 展開を使用して参照するには、`${CLAUDE_PROJECT_DIR:-.}` などのデフォルトが必要です。プラグイン提供の MCP 設定は `${CLAUDE_PROJECT_DIR}` を直接置換し、デフォルトは必要ありません。131この変数はサーバーの環境に設定され、Claude Code 自体の環境には設定されないため、プロジェクトスコープの `.mcp.json` エントリまたはローカルまたはユーザースコープのサーバーエントリの `command` または `args` で `${VAR}` 展開を使用して参照するには、`${CLAUDE_PROJECT_DIR:-.}` などのデフォルトが必要です。プラグイン提供の MCP 設定は `${CLAUDE_PROJECT_DIR}` を直接置換し、デフォルトは必要ありません。

121 132 

122```bash theme={null}133```bash theme={null}

123# 基本的な構文134# 基本的な構文

124claude mcp add [options] <name> -- <command> [args...]135claude mcp add [options] <name> -- <command> [args...]

125 136 

126# 実際の例：Airtable サーバーを追加する137# 実際の例: Airtable サーバーを追加

127claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \138claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \

128 -- npx -y airtable-mcp-server139 -- npx -y airtable-mcp-server

129```140```

130 141 

131<Note>142<Note>

132 **重要：サーバー引数を `--` で分離する**143 **重要: サーバー引数を `--` で区切る**

133 144 

134 Stdio サーバーの場合、`--`（ダブルダッシュ）は Claude 自体のオプション（`--transport`、`--env`、`--scope` など）をサーバーを実行するコマンドと引数から分離します。`--` の後のすべてはサーバーに変更されずに渡されます。145 Stdio サーバーの場合、`--`（ダブルダッシュ）は Claude 自体のオプション（`--transport`、`--env`、`--scope` など）をサーバーを実行するコマンドと引数から分離します。`--` の後のすべてはサーバーに変更されずに渡されます。

135 146 

136 例：147 例えば：

137 148 

138 * `claude mcp add --transport stdio myserver -- npx server` → `npx server` を実行します149 * `claude mcp add --transport stdio myserver -- npx server` → `npx server` を実行します

139 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 環境に `KEY=value` を設定して `python server.py --port 8080` を実行します150 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 環境に `KEY=value` を設定して `python server.py --port 8080` を実行します

140 151 

141 `--` がない場合、Claude Code はサーバーのフラグ（上記の `--port` など）を独自のオプションとして解析しようとします。152 `--` がない場合、Claude Code はサーバーのフラグ（上記の `--port` など）を独自のオプションとして解析しようとします。

142 153 

143 `--env` は複数の `KEY=value` ペアを受け入れます。サーバー名が `--env` の直後に来る場合、CLI は名前を別のペアとして読み取り、それを拒否するため、上記の例のように `--env` とサーバー名の間に少なくとも 1 つの別のオプションを配置してください。154 `--env` は複数の `KEY=value` ペアを受け入れます。サーバー名が `--env` の直後に来る場合、CLI は名前を別のペアとして読み込み、拒否するため、上記の例のように `--env` とサーバー名の間に少なくとも 1 つの別のオプションを配置してください。

144</Note>155</Note>

145 156 

146<h3 id="option-4-add-a-remote-websocket-server">157<h3 id="option-4-add-a-remote-websocket-server">

147 オプション 4：リモート WebSocket サーバーを追加する158 オプション 4: リモート WebSocket サーバーを追加する

148</h3>159</h3>

149 160 

150WebSocket サーバーは永続的な双方向接続を保持し、Claude に予期しないイベントをプッシュするリモート MCP サーバーに適しています。サーバーがリクエストにのみ応答する場合は HTTP を使用してください。HTTP は OAuth と `claude mcp add --transport` フラグをサポートしていますが、WebSocket はどちらもサポートしていません。161WebSocket サーバーは永続的な双方向接続を保持し、Claude に予期しないイベントをプッシュするリモート MCP サーバーに適しています。サーバーがリクエストにのみ応答する場合は HTTP を使用してください。HTTP は OAuth と `claude mcp add --transport` フラグをサポートしますが、WebSocket はどちらもサポートしていないためです。

151 162 

152WebSocket サーバーを `.mcp.json` または `claude mcp add-json` で設定します：163WebSocket サーバーを `.mcp.json` または `claude mcp add-json` で設定します。

153 164 

154```bash theme={null}165```bash theme={null}

155claude mcp add-json events-server \166claude mcp add-json events-server \

156 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'167 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

157```168```

158 169 

159`type: "ws"` エントリは `http` と同じ `url`、`headers`、`headersHelper`、`timeout`、`alwaysLoad` フィールドを受け入れます。認証はヘッダーのみなので、`headers` に静的トークンを渡すか、[`headersHelper`](#use-dynamic-headers-for-custom-authentication) で接続時に生成してください。`claude mcp add --transport` フラグは `ws` を受け入れません。170`type: "ws"` エントリは `http` と同じ `url`、`headers`、`headersHelper`、`timeout`、`alwaysLoad` フィールドを受け入れます。認証はヘッダーのみなので、`headers` に静的トークンを渡すか、接続時に [`headersHelper`](#use-dynamic-headers-for-custom-authentication) で生成してください。`claude mcp add --transport` フラグは `ws` を受け入れません。

171 

172<h3 id="add-a-server-from-setup-instructions-written-for-another-client">

173 別のクライアント向けに書かれたセットアップ指示からサーバーを追加する

174</h3>

175 

176MCP サーバーは Claude Code に固有ではないため、サーバーのセットアップ指示は Claude Desktop、Cursor、または別の MCP クライアント向けに書かれている可能性があり、`claude mcp add` コマンドを提供していない場合があります。それでもサーバーを追加するには、これら 3 つのいずれかについて指示を確認してください。

177 

178* **URL**（`https://mcp.example.com/mcp` など）: サーバーはリモートです。

179* **起動コマンド**（`npx -y @example/mcp-server` など）: サーバーはマシン上で実行されます。

180* **`mcpServers` JSON ブロック**: 別のクライアントの設定ファイル向けに書かれた設定。

181 

182各々は [MCP サーバーのインストール](#installing-mcp-servers) の 4 つのオプションが取る入力の 1 つです。以下で持っている形状を見つけて、Claude Code が受け入れるコマンドに変換してください。各コマンドは `--scope project` または `--scope user` を追加しない限り、[ローカルスコープ](#local-scope) に書き込みます。

183 

184<h4 id="from-a-url">

185 URL から

186</h4>

187 

188URL はサーバーがリモートであることを意味します。`https://` エンドポイントの場合、`--transport http` で追加するか、指示が SSE を使用するエンドポイントを示している場合は [オプション 2](#option-2-add-a-remote-sse-server) に従ってください。`wss://` エンドポイントの場合、`--transport` は `ws` を受け入れないため、代わりに [オプション 4](#option-4-add-a-remote-websocket-server) を使用してください。

189 

190```bash theme={null}

191claude mcp add --transport http example https://mcp.example.com/mcp

192```

193 

194指示が API キーまたはトークンヘッダーも提供する場合、[オプション 1](#option-1-add-a-remote-http-server) に示されているように `--header` で渡してください。

195 

196<h4 id="from-an-npx-uvx-or-binary-command">

197 `npx`、`uvx`、またはバイナリコマンドから

198</h4>

199 

200起動コマンドはサーバーがローカル stdio プロセスとして実行されることを意味します。コマンド全体を `--` の後に配置して、Claude Code が `-y` などのフラグをサーバーを起動するコマンドに渡し、独自のオプションとして読み込まないようにします。指示が要求する環境変数を `--env` で渡します。サーバー名の後、`--` の前に渡します。

201 

202```bash theme={null}

203claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

204```

205 

206[オプション 3](#option-3-add-a-local-stdio-server) は `--` セパレータを完全にカバーしています。

207 

208<h4 id="from-an-mcpservers-json-block">

209 `mcpServers` JSON ブロックから

210</h4>

211 

212Claude Desktop などの別の MCP クライアント向けに書かれた `mcpServers` ブロックは、Claude Code が読み込むラッパーキーとエントリ形状を使用します。`claude mcp add-json` に `mcpServers` 内のオブジェクトを渡します。ラッパーではなく。2 つのエントリは最初に修復が必要です。

213 

214* **`type` のない `url`**: エンドポイントに一致するように `"type": "http"`、`"type": "sse"`、または `"type": "ws"` を追加してください。Claude Code は `type` を持たないエントリを stdio サーバーとして読み込むため、`type` のない `url` エントリは失敗します。

215* **文字、数字、ハイフン、アンダースコア以外の文字を持つキー**: これらの文字のみを使用するサーバー名を選択してください。そうでない場合、キーはサーバー名です。

216 

217例えば、このブロック：

218 

219```json theme={null}

220{

221 "mcpServers": {

222 "example": {

223 "command": "npx",

224 "args": ["-y", "@example/mcp-server"]

225 }

226 }

227}

228```

229 

230このコマンドになります：

231 

232```bash theme={null}

233claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

234```

235 

236[JSON 設定から MCP サーバーを追加する](#add-mcp-servers-from-json-configuration) はシェルエスケープと `add-json` の `--scope` フラグをカバーしています。代わりにチームと共有するには、`--scope project` を追加するか、プロジェクトルートの `.mcp.json` の `mcpServers` の下にエントリを追加してコミットしてください。[プロジェクトスコープ](#project-scope) は Claude Code がそのファイルをどのように読み込み、承認するかをカバーしています。

237 

238各 `claude mcp add` と `claude mcp add-json` コマンドは `Added ...` 行を出力します。Claude Code が接続したことを確認するには、`claude mcp get <name>` を実行してください。[サーバーステータス](#server-status) はそれが表示するステータスと `.mcp.json` サーバーの承認ステップをカバーしています。

160 239 

161<h3 id="managing-your-servers">240<h3 id="managing-your-servers">

162 サーバーの管理241 サーバーの管理

163</h3>242</h3>

164 243 

165設定後、これらのコマンドで MCP サーバーを管理できます：244設定されたら、これらのコマンドで MCP サーバーを管理できます。

166 245 

167```bash theme={null}246```bash theme={null}

168# すべての設定済みサーバーをリストする247# すべての設定されたサーバーをリストする

169claude mcp list248claude mcp list

170 249 

171# 特定のサーバーの詳細を取得する250# 特定のサーバーの詳細を取得する

172claude mcp get github251claude mcp get notion

173 252 

174# サーバーを削除する253# サーバーを削除する

175claude mcp remove github254claude mcp remove notion

176 255 

177# （Claude Code 内）サーバーのステータスを確認する256# （Claude Code 内）サーバーステータスを確認する

178/mcp257/mcp

179```258```

180 259 

181`.mcp.json` からのプロジェクトスコープサーバーで承認待ちのものは、`claude mcp list` に `⏸ Pending approval` として表示されます。`claude` をインタラクティブに実行して、それらを確認して承認してください。`claude mcp get <name>` は保留中のサーバーを `⏸ Pending approval` として表示し、拒否されたサーバーを `✗ Rejected` として表示します。260リモートサーバーを削除すると、Claude Code はそのサーバー用に保存した OAuth トークンとクライアント登録も削除します。

261 

262<h4 id="server-status">

263 サーバーステータス

264</h4>

265 

266`claude mcp add` は `Added ...` 行を出力して成功した追加を確認します。これは設定が書き込まれたことを意味します。`claude mcp list` はその後、`✔ Connected`、`! Needs authentication`、`✘ Failed to connect` などの各サーバーの横に健全性ステータスを表示します。失敗ステータスは Claude Code がそのサーバーに接続できなかったことを意味し、list コマンドが失敗したことではありません。

182 267 

183v2.1.196 以降、`claude mcp list` と `claude mcp get` は、リポジトリにチェックインされていない設定ファイルからのみ `.mcp.json` 承認を読み取ります。これは、`claude` を実行してワークスペーストラストダイアログを受け入れることでワークスペースを信頼するまでです。クローンされたリポジトリは独自のサーバーを承認できません：プロジェクトの `.claude/settings.json` にコミットされた [`enableAllProjectMcpServers` または `enabledMcpjsonServers`](/docs/ja/settings#available-settings) は信頼されていないフォルダでは無視され、サーバーは接続されてヘルスチェックされる代わりに `⏸ Pending approval` のままです。268このリストのステータスは接続試行ではなく設定決定を報告するため、Claude Code はサーバーに接続せずにそれらを出力します。

184 269 

185これらのソースからの承認は、信頼されていないフォルダでも適用されます：270* ``⏸ Pending approval (run `claude` to approve)``: まだ承認していない `.mcp.json` からのプロジェクトスコープサーバー。Claude Code はそれを `claude mcp list` と `claude mcp get <name>` の両方に表示します。対話的に `claude` を実行して、それを確認して承認してください。

271* `✘ Rejected (see disabledMcpjsonServers in settings)`: [`disabledMcpjsonServers`](/docs/ja/settings-reference#disabledmcpjsonservers) エントリが拒否する `.mcp.json` サーバー。Claude Code はそれを `claude mcp get <name>` にのみ表示します。

272* `⊘ Disabled for this project (re-enable via /mcp)`: プロジェクトの [`disabledMcpServers`](#disable-a-server-without-removing-it) リストが名前を付けるサーバー。Claude Code はそれを `claude mcp list` と `claude mcp get <name>` の両方に表示します。`/mcp` パネルからサーバーをオンに戻してください。v2.1.238 より前では、両方のコマンドが無効なサーバーに接続して健全性チェックを実行し、接続結果を報告していました。

186 273 

187* ユーザーの `~/.claude/settings.json`274WebSocket サーバーは `claude mcp list` 出力に表示されません。`claude mcp get <name>` または `/mcp` パネルを使用してそれらを確認してください。

275 

276<h4 id="project-server-approvals-and-workspace-trust">

277 プロジェクトサーバーの承認とワークスペーストラスト

278</h4>

279 

280v2.1.196 以降、`claude mcp list` と `claude mcp get` は `.mcp.json` 承認を、`claude` を実行してワークスペーストラストダイアログを受け入れるまでリポジトリにチェックインされていない設定ファイルからのみ読み込みます。クローンされたリポジトリは独自のサーバーを承認できません。プロジェクトの `.claude/settings.json` にコミットされた [`enableAllProjectMcpServers`](/docs/ja/settings-reference#enableallprojectmcpservers) または [`enabledMcpjsonServers`](/docs/ja/settings-reference#enabledmcpjsonservers) は信頼されていないフォルダでは無視され、サーバーは接続されて健全性チェックされる代わりに `⏸ Pending approval` のままです。

281 

282これらのソースからの承認は信頼されていないフォルダでも適用されます。

283 

284* ユーザー `~/.claude/settings.json`

188* 管理設定285* 管理設定

189* `--settings` で渡された設定286* `--settings` で渡された設定

190 287 

191トラッキングされていない `.claude/settings.local.json` の承認も適用されますが、そのフォルダまたはその親ディレクトリのいずれかに対してトラストダイアログを受け入れた後のみです：Claude Code は git を実行してファイルがトラッキングされているかどうかを確認し、その確認は信頼されたフォルダでのみ実行されます。信頼したことのないフォルダでは、ファイルの承認はトラストダイアログを待ちます。ただし、フォルダがあなた自身の設定ホーム（ホームディレクトリ、または `.claude` を [`CLAUDE_CONFIG_DIR`](/docs/ja/env-vars) として設定したディレクトリ）である場合は除きます。v2.1.207 より前は、トラッキングされていない `.claude/settings.local.json` は信頼したことのないフォルダのサーバーを承認していました。288Claude Code はまた、追跡されていない `.claude/settings.local.json` からの承認を適用しますが、ファイルが追跡されているかどうかを確認するために git を実行し、その確認は [信頼されたフォルダ](/docs/ja/permissions#project-allow-rules-and-workspace-trust) でのみ実行されます。信頼したことのないフォルダでは、Claude Code はトラストダイアログを待ってからファイルの承認を適用します。ただし、フォルダがユーザー自身の設定ホームである場合は除きます。ホームディレクトリ、または `.claude` を [`CLAUDE_CONFIG_DIR`](/docs/ja/env-vars) として設定したディレクトリ。v2.1.207 より前では、Claude Code は信頼したことのないフォルダでも追跡されていない `.claude/settings.local.json` からの承認を適用していました。

289 

290任意の設定ファイルの `disabledMcpjsonServers` エントリはまだサーバーを拒否します。

192 291 

193任意の設定ファイル内の `disabledMcpjsonServers` エントリはサーバーを拒否します。292<h4 id="server-status-detail">

293 サーバーステータスの詳細

294</h4>

194 295 

195`/mcp` パネルは、接続されている各サーバーの横にツール数を表示し、ツール機能をアドバタイズしているが、ツールを公開していないサーバーにフラグを立てます。296`/mcp` で、そこにあるサーバーのメニューを含めて、[`/plugin`](/docs/ja/plugins) マネージャーで、以前使用したリモート HTTP または SSE サーバーは `cached` ステータス（`cached 2h ago · connects on first use · 5 tools` など）を表示できます。Claude Code は起動時に接続する代わりに、前のセッションで保存された検出キャッシュからサーバーのツールリストを読み込み、Claude Code はサーバーのツールの 1 つを Claude が最初に呼び出すときにサーバーを接続します。ツールは最初のメッセージから利用可能なため、何もする必要はありません。検出キャッシュとその `cached` ステータスには Claude Code v2.1.221 以降が必要です。

196 297 

197設定に空の `url` を持つリモートサーバーは、`/mcp`、`claude mcp list`、および [`/plugin`](/docs/ja/plugins) マネージャーに `not configured` として表示され、Claude Code は接続を試みません。プラグインは、後で設定するコネクタ用のプレースホルダーエントリを含めることができるため、Claude Code はそれをエラーまたはセットアップの問題として報告しません。`/mcp` のサーバーの詳細ビューは `No URL configured for this server` と表示されます。接続するにはエントリの `url` を設定してください。v2.1.208 より前は、Claude Code は空の `url` を設定の問題として報告し、再接続を促すプロンプトを表示していました。298検出キャッシュはデフォルトではオフですが、段階的なロールアウトがアカウントに対して有効にしている場合を除きます。[`MCP_DISCOVERY_CACHE=1`](/docs/ja/env-vars) を設定してオンにするか、`0` を設定してロールアウトが有効にしている場合でもオフのままにしてください。v2.1.238 より前では、キャッシュはデフォルトでオンでした。

198 299 

199リクエストがまだバックグラウンドで接続中のサーバーからのツールを必要とする場合、Claude はそのサーバーが接続されるまで待機してから続行します。デフォルトで有効になっている [ツール検索](#scale-with-mcp-tool-search) を使用すると、待機は `ToolSearch` 呼び出し内で発生します。Google Cloud の Agent Platform、カスタム `ANTHROPIC_BASE_URL`、または `ENABLE_TOOL_SEARCH=false` などのツール検索がない設定では、Claude は代わりに `WaitForMcpServers` ツールを使用します。300`/mcp` のサーバーのメニューの 2 つのアクションもそのサーバーのキャッシュエントリに影響します。

200 301 

201一部のサーバー名は Claude Code の組み込みサーバー用に予約されています：`workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview`、`Claude Browser`。設定がこれらの予約名のいずれかでサーバーを定義している場合、Claude Code はロード時にそれをスキップし、名前を変更するよう求める警告を表示します。`claude mcp add` は予約名をエラーで拒否します。302* **再接続**: `cached` サーバーで、Claude Code は最初のツール呼び出しではなく今すぐそれを接続し、エントリを保持します。接続されたまたは失敗したサーバーで、Claude Code はそれを再接続し、エントリも破棄します。

303* **認証をクリア**: Claude Code はサーバーの認証を取り消し、エントリも破棄します。

202 304 

203`Claude Preview` と `Claude Browser` は両方とも、[Claude Code デスクトップアプリのプレビューペイン](/docs/ja/desktop#preview-your-app) が使用する組み込みサーバーに名前を付けます。v2.1.205 より前は、`Claude Browser` は予約されていなかったため、ユーザーが設定したサーバーはその名前で登録できました。305エントリを破棄した後、Claude Code はキャッシュではなくサーバーからサーバーのツールリストを取得します。

306 

307サーバーのステータスが `✘ Failed to connect` の場合、`claude mcp list` はそのステータス行に失敗の詳細を追加し、`claude mcp get <name>` は `Issue:` 行に表示します。HTTP ステータスまたはエラーコード、およびサーバーが返したエラーテキスト。サーバーの詳細ビューは `/mcp` で同じサーバー報告テキストを `Issue:` 行に含めます。Claude Code はこの詳細から認証情報のようなテキストを編集し、展開されたサーバー URL を含めることはありません。これはシークレットを運ぶことができます。Claude Code は `✘ Connection error` ステータスに詳細を追加しません。例外テキストがそこに出力される可能性があるため、その URL を埋め込むことができます。v2.1.219 より前では、両方のコマンドはステータスコードまたはサーバーのエラーテキストなしで、単なる失敗ステータスのみを表示していました。

308 

309`/mcp` から認証を完了し、接続が HTTP ステータスまたはトランスポートエラーコードで失敗し続ける場合、Claude Code は試行後に出力するメッセージにそのコードとサーバーの URL の起点を追加します。起点はスキーム、ホスト、およびポート（URL が 1 つを名前付けする場合）です。例えば `https://mcp.example.com`。

310 

311* パスとクエリはそのメッセージに表示されません。

312* ローカル、プロジェクト、またはユーザー [スコープ](#mcp-installation-scopes) のサーバー、または管理 MCP 設定のサーバーの場合、起点はその設定に書き込まれたホストを表示するため、ホストの `${VAR}` 参照はメッセージで展開されません。

313* ステータスまたはエラーコードのない失敗の場合、Claude Code は起点なしでエラーテキストを表示します。

314 

315設定に空の `url` を持つリモートサーバーは `/mcp`、`claude mcp list`、[`/plugin`](/docs/ja/plugins) マネージャーで `not configured` として表示され、Claude Code はそれに接続しようとしません。プラグインは後で設定するコネクタのプレースホルダーエントリをこのように含めることができるため、Claude Code はそれをエラーまたはセットアップの問題として報告しません。サーバーの詳細ビューは `/mcp` で `No URL configured for this server` を読み込みます。接続するにはエントリの `url` を設定してください。v2.1.208 より前では、Claude Code は空の `url` を設定の問題として報告し、再接続を促していました。

316 

317<h4 id="configuration-warnings">

318 設定警告

319</h4>

320 

321Claude Code は以下の設定の問題について警告します。各エントリは Claude Code が何をチェックし、警告をクリアする方法を示しています。

322 

323* **隠れた空白**: Claude Code は MCP 設定値が隠れた先頭または末尾の空白を持つときに警告します。これはしばしば末尾の改行を持つトークンを貼り付けることから来ます。Claude Code は `command`、`url`、各 `args` エントリ、および `env` と `headers` の下の値とキー名をチェックします。Claude Code は警告を `claude mcp list` 出力と `/mcp` に表示し、影響を受けたフィールドに名前を付けます。例えば `Leading or trailing whitespace in: headers.Authorization`。Claude Code は空白をトリムしません。書き込まれたとおりに値を使用するため、設定を編集してそれを削除してください。

324* **複数のスコープで同じ名前**: 異なるエンドポイントで複数の [スコープ](#mcp-installation-scopes) で同じサーバー名を定義する場合、Claude Code は `claude mcp list` 出力と `/mcp` で競合について警告します。Claude Code は OAuth サインインをエンドポイントごとに保存するため、1 つのプロジェクトで読み込まれる定義を認証すると、別の定義が読み込まれるプロジェクトで別にサインインする必要があります。必要なエンドポイントを保持し、他を `claude mcp remove <name> --scope <scope>` で削除してください。警告では、Claude Code は各スコープのエンドポイントを設定に書き込まれたとおりに引用します。[`${VAR}` 参照](#environment-variable-expansion-in-mcp-json) は展開されないため、API キーなどの解決された値を表示しません。

325* **予約名**: Claude Code は `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview`、`Claude Browser` を含む組み込みサーバーの名前を予約しています。設定が予約名を持つサーバーを定義する場合、Claude Code はロード時にそれをスキップし、名前を変更するよう求める警告を表示します。`claude mcp add` は予約名を拒否します。`Claude Preview` と `Claude Browser` は両方とも [Claude Code デスクトップアプリのプレビューペイン](/docs/ja/desktop#preview-your-app) が使用する組み込みサーバーに名前を付けます。v2.1.205 より前では、`Claude Browser` は予約されていなかったため、ユーザー設定サーバーはその名前で登録できました。

326* **環境変数の欠落**: サーバーの設定の [`${VAR}` 参照](#environment-variable-expansion-in-mcp-json) が設定されていない変数に名前を付け、`:-default` がない場合、Claude Code は `claude mcp list` 出力と `/mcp` で警告し、変数に名前を付けます。`${VAR}` テキストは展開されないままサーバーを読み込みます。変数を設定するか、`${VAR:-default}` フォールバックを追加してください。

327 

328<h4 id="tool-availability">

329 ツール可用性

330</h4>

331 

332`/mcp` パネルは各接続されたサーバーの横にツール数を表示し、ツール機能をアドバタイズするがツールを公開しないサーバーにフラグを立てます。

333 

334リクエストがバックグラウンドでまだ接続中のサーバーからのツールを必要とする場合、Claude はそのサーバーが接続するまで待機します。待機の方法は設定によって異なります。

335 

336* **[ツール検索](#scale-with-mcp-tool-search)（デフォルト）を使用**: 待機は `ToolSearch` 呼び出し内で発生します。

337* **ツール検索なし**: Claude は代わりに `WaitForMcpServers` ツールを使用します。ツール検索なしの設定には、カスタム `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false`、Google Cloud の Agent Platform の Claude 4.5 世代より前のモデルが含まれます。

338* **Microsoft Foundry [Azure でホストされたデプロイメント](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: Claude はツール検索パスで開始します。Claude Code は API からのデプロイメントのサーバー側拒否のみを検出するため、`WaitForMcpServers` ではなく。Claude Code がそのデプロイメントを [アップフロント読み込み](#scale-with-mcp-tool-search) に切り替えた後、サーバーが接続を完了するからのツールは Claude の次のリクエストで利用可能になります。

339 

340ツール検索が有効な場合、サーバーが Claude が作業中に接続を完了すると、Claude Code はサーバーのツール名を同じターンの次のリクエストで Claude にリストします。Claude はそれらのツールを検索して呼び出し、メッセージを待つことなく実行できます。

341 

342<h3 id="disable-a-server-without-removing-it">

343 サーバーを削除せずに無効にする

344</h3>

345 

346`/mcp` パネルでサーバーをオフに切り替えて、Claude Code がそれに接続するのを停止し、設定を失わないようにします。Claude Code はサーバーを `/mcp` にリストし、無効としてマークします。

347 

348サーバーを切り替えると、Claude Code はプロジェクトごとに `~/.claude.json` で選択を記録します。2 つのリストの 1 つで、互いに素なサーバーセットをカバーします。

349 

350* `disabledMcpServers`: ユーザー設定サーバー、プラグインサーバー、組織が [管理設定を通じて提供](/docs/ja/managed-mcp#provide-servers-through-managed-settings) するサーバー、Claude Code が [自身で取得](#how-connectors-reach-claude-code) する claude.ai コネクタ、およびデフォルトでオンの組み込みサーバーのオプトアウトリスト。Claude Code はここにリストするサーバーに接続しません。[Disable claude.ai connectors](#disable-claude-ai-connectors) で説明されているプロジェクトごとの `/mcp` トグルで claude.ai コネクタを無効にすると、Claude Code はそれをこのリストの下に表示名で書き込みます。例えば `claude.ai Slack`。

351* `enabledMcpServers`: `computer-use` などのデフォルトでオフの組み込みサーバーのオプトインリスト。Claude Code はここにリストする場合にのみデフォルトオフサーバーに接続します。

352 

353Claude Code は各サーバーに対して 2 つのリストの 1 つを正確に参照するため、どちらのリストも他をオーバーライドしません。通常のサーバーを `enabledMcpServers` に追加するか、デフォルトオフの組み込みサーバーを `disabledMcpServers` に追加する場合、Claude Code はエントリを無視します。

354 

355`disabledMcpServers` と `enabledMcpServers` は [`enabledMcpjsonServers`](/docs/ja/settings-reference#enabledmcpjsonservers) と [`disabledMcpjsonServers`](/docs/ja/settings-reference#disabledmcpjsonservers) とは無関係です。これらはプロジェクトの `.mcp.json` ファイルで定義されたサーバーの承認を制御します。

356 

357<h3 id="mcp-client-runtimes">

358 MCP クライアントランタイム

359</h3>

360 

361Claude Code は 2 つのクライアントランタイムの 1 つを通じて MCP サーバーに接続します。v1 ランタイムは MCP TypeScript SDK 1.x に基づいています。v2 ランタイムは [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上の同じコードで、MCP プロトコルリビジョン 2026-07-28 を追加します。このページの残りは両方のランタイムに適用されます。ただし、セクションが v2 ランタイムに名前を付ける場合を除きます。

362 

363Claude Code v2.1.232 以降では、Claude Code は v2 ランタイムを使用します。起動するたびにランタイムを選択し、終了するまで保持します。これを実行する場合は v1 を使用します。

364 

365* Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、または Microsoft Foundry で。ただし、Claude Code を埋め込むホストプラットフォームが [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ja/env-vars) を設定する場合を除きます

366* [Claude apps gateway](/docs/ja/claude-apps-gateway) を通じてサインイン

367* [フィーチャーフラグ取得がオフ](/docs/ja/env-vars#features-that-need-feature-flag-fetching)

368 

369v2 では、Claude Code も：

370 

371* HTTP と claude.ai コネクタサーバーに新しいリビジョンをサポートするかどうかを尋ね、それをサポートするサーバーで使用します。Stdio サーバーに尋ねるのは [`MCP_PROTOCOL_NEGOTIATION`](/docs/ja/env-vars) を `auto` に設定する場合のみで、他のすべてのサーバーに v1 のように接続します。

372* 新しいリビジョンのサーバーから [ストリームを保持](#notification-streams-on-the-v2-runtime) 上で `list_changed` 通知を受け取ります。

373* 新しいリビジョンで接続する [チャネル](#push-messages-with-channels) サーバーを登録しません。そのリビジョンはチャネルメッセージを運ぶことができないためです。

374* 予期しない発行者に名前を付ける認可応答の [MCP OAuth サインイン](#authenticate-with-remote-mcp-servers) に失敗します。

375 

376Anthropic は特定のサーバーを以前のプロトコルに保つか、Claude Code が取得するフィーチャーフラグでそのストリームをオフにすることができます。

377 

378ランタイムを自分で選択するには、[`MCP_SDK_GENERATION`](/docs/ja/env-vars) を `v1` または `v2` に設定してください。Claude Code が尋ねるかどうかを決定するには、[`MCP_PROTOCOL_NEGOTIATION`](/docs/ja/env-vars) を `auto` または `legacy` に設定してください。Claude Code がデフォルトで v1 を使用する場合、`v2` をピン留めしても尋ねません。`auto` も設定してください。

204 379 

205<h3 id="dynamic-tool-updates">380<h3 id="dynamic-tool-updates">

206 動的ツール更新381 動的ツール更新

207</h3>382</h3>

208 383 

209Claude Code は MCP `list_changed` 通知をサポートしており、MCP サーバーが切断して再接続することなく、利用可能なツール、プロンプト、リソースを動的に更新できます。MCP サーバーが `list_changed` 通知を送信すると、Claude Code はそのサーバーから利用可能な機能を自動的に更新します。384Claude Code は MCP `list_changed` 通知をサポートし、MCP サーバーが切断して再接続することなく利用可能なツール、プロンプト、リソースを動的に更新できます。MCP サーバーが `list_changed` 通知を送信すると、Claude Code は自動的にそのサーバーから利用可能な機能をリフレッシュします。

385 

386リフレッシュリクエストが失敗する場合、Claude Code はサーバーの以前に検出されたツール、プロンプト、リソースを保持します。後のリフレッシュが成功するまで。v2.1.214 より前では、リフレッシュ中の一時的なエラーはサーバーのツール、プロンプト、リソースを空のリストに置き換えていました。

387 

388<h4 id="notification-streams-on-the-v2-runtime">

389 v2 ランタイムの通知ストリーム

390</h4>

391 

392[v2 ランタイム](#mcp-client-runtimes) では、Claude Code は新しいプロトコルリビジョンのサーバーから保持するストリーム上で `list_changed` 通知を受け取ります。ストリームが閉じると、Claude Code はそれを再度開きます。2 つの制限があります。

393 

394* **ストリームが 10 秒以内に再度閉じる**: Claude Code はそれを最大 3 回再度開き、その接続に対して停止します。

395* **ストリームが 10 秒以上開いたままで、その後閉じる**。サーバーレスホストへのストリームが一般的に行うように。1 時間に 5 回再度開いた後、Claude Code は次のものまで約 6 時間待機します。

396 

397ストリームが再度開くまで、サーバーの最後に取得したツール、プロンプト、リソースを保持します。変更をより早く取得するには、`/mcp` からサーバーを再接続してください。

210 398 

211<h3 id="automatic-reconnection">399<h3 id="automatic-reconnection">

212 自動再接続400 自動再接続

213</h3>401</h3>

214 402 

215HTTP または SSE サーバーがセッション中に切断された場合、Claude Code は指数バックオフで自動的に再接続します：最大 5 回の試行、1 秒の遅延から始まり、毎回 2 倍になります。サーバーは再接続が進行中の間、`/mcp` では保留中として表示されます。5 回の失敗した試行の後、サーバーは失敗としてマークされ、`/mcp` から手動で再試行できます。Stdio サーバーはローカルプロセスであり、自動的には再接続されません。403Claude Code はセッション中にドロップするリモートサーバーを再接続し、一時的なエラーの後に HTTP または SSE サーバーの最初の接続を再試行します。Stdio サーバーはローカルプロセスであり、Claude Code は自動的にそれらを再接続しません。

404 

405<h4 id="mid-session-drops-of-a-remote-server">

406 リモートサーバーのセッション中のドロップ

407</h4>

408 

409Claude Code は指数バックオフでドロップされたリモートサーバーを再接続します。最大 5 回の試行。1 秒の遅延で開始し、毎回それを 2 倍にします。表示内容は Claude Code の実行方法によって異なります。

410 

411* **対話的セッション**: `/mcp` は Claude Code が再接続している間、サーバーを保留中として表示します。5 回の失敗した試行の後、Claude Code はサーバーを失敗としてマークするか、サーバーが再度認可する必要がある場合は認証が必要として。`/mcp` から手動で再試行できます。

412* **[`claude -p`](/docs/ja/headless) 実行と [Agent SDK](/docs/ja/agent-sdk/overview) セッション**: Claude Code は同じスケジュールで再接続し、試行を表示する `/mcp` パネルはありません。

216 413 

217同じバックオフは、HTTP または SSE サーバーが起動時に初期接続に失敗した場合にも適用されます。v2.1.121 以降、Claude Code は 5xx レスポンス、接続拒否、タイムアウトなどの一時的なエラーで初期接続を最大 3 回再試行し、それでも接続できない場合はサーバーを失敗としてマークします。認証エラーと見つからないエラーは、解決するために設定変更が必要なため、再試行されません。414<h4 id="failed-first-connections">

415 失敗した最初の接続

416</h4>

218 417 

219設定されたサーバーが接続に失敗した場合、Claude Code は Claude にどのサーバーが失敗したかとその接続エラーを伝えます。これは、マッチするツールが見つからない `ToolSearch` 結果を含みます。そのため、Claude は応答で接続失敗を報告します。[ツール検索](#scale-with-mcp-tool-search) が必要です。これはデフォルトで有効になっています。カスタム `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false`、または Haiku モデルなどのツール検索がない設定、および Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry では、Claude Code は失敗したサーバー接続を Claude に報告しません。v2.1.205 より前は、Claude Code は接続エラーを Claude に渡さず、Claude は失敗したサーバーのツールが設定されていないかのように応答できました。418HTTP または SSE サーバーの最初の接続が 5xx レスポンス、接続拒否、タイムアウトなどの一時的なエラーで失敗する場合、Claude Code は最大 3 回再試行します。接続がまだ失敗する場合、Claude Code はサーバーを失敗としてマークします。Claude Code はこのように起動時と、セッション中にサーバーが追加されるときに再試行します。これには Claude Code が [クラウドセッション](/docs/ja/claude-code-on-the-web) に設定から追加するサーバーと、Agent SDK の [`setMcpServers()`](/docs/ja/agent-sdk/typescript) で追加するサーバーが含まれます。

220 419 

221v2.1.191 以降、接続成功後に実行される機能検出リクエスト（`tools/list`、`prompts/list`、`resources/list` など）も、一時的なネットワークおよびサーバーエラーを短いバックオフで最大 3 回再試行します。認証エラー、4xx レスポンス、リクエストタイムアウトは再試行されません。420Claude Code はこれらの場合には再試行しません。

421 

422* WebSocket サーバーの最初の接続

423* 認証またはエラーが見つからない。設定変更を解決する必要があるため。[`headersHelper`](#use-dynamic-headers-for-custom-authentication) がサーバーの `Authorization` ヘッダーの唯一のソースである場合、Claude Code は認証エラーを再試行します。ヘルパーを各試行で再実行し、新しい認証情報を取得できるためです。

424 

425<h4 id="failed-discovery-requests">

426 失敗した検出リクエスト

427</h4>

428 

429サーバーが接続した後、Claude Code は `tools/list`、`prompts/list`、`resources/list` などの機能検出リクエストを送信します。Claude Code は一時的なネットワークまたはサーバーエラーの後、短いバックオフで最大 3 回それらのリクエストを再試行します。認証エラー、4xx レスポンス、またはリクエストタイムアウトは再試行しません。

430 

431<h4 id="how-claude-learns-that-a-server-failed">

432 Claude がサーバーが失敗したことを学ぶ方法

433</h4>

434 

435Claude Code が接続に失敗した設定されたサーバーについて Claude に伝えるかどうかは [ツール検索](#scale-with-mcp-tool-search)（デフォルトではオン）に依存します。

436 

437* ツール検索を使用して、Claude Code は Claude にどのサーバーが失敗したか、その接続エラーを伝えるため、Claude は応答で接続失敗を報告します。Claude Code は一致するツールを見つけない `ToolSearch` 結果に同じ情報を含めます。

438* [ツール検索なしの設定](#configure-tool-search) では、Claude Code は失敗したサーバー接続を Claude に報告しません。

222 439 

223<h3 id="push-messages-with-channels">440<h3 id="push-messages-with-channels">

224 チャネルでメッセージをプッシュする441 チャネルでメッセージをプッシュする

225</h3>442</h3>

226 443 

227MCP サーバーはセッションに直接メッセージをプッシュすることもでき、Claude が CI 結果、監視アラート、チャットメッセージなどの外部イベントに対応できます。これを有効にするには、サーバーが `claude/channel` 機能を宣言し、起動時に `--channels` フラグでオプトインします。公式にサポートされているチャネルを使用するには [チャネル](/docs/ja/channels) を参照するか、独自に構築するには [チャネルリファレンス](/docs/ja/channels-reference) を参照してください。444MCP サーバーはまた、CI 結果、監視アラート、チャットメッセージなどの外部イベントに Claude が反応できるようにメッセージをセッションに直接プッシュできます。これを有効にするには、サーバーが `claude/channel` 機能を宣言し、起動時に `--channels` フラグでオプトインします。[チャネル](/docs/ja/channels) を使用して公式にサポートされているチャネルを使用するか、[チャネルリファレンス](/docs/ja/channels-reference) を参照して独自に構築してください。

445 

446[v2 ランタイム](#mcp-client-runtimes) では、[`MCP_PROTOCOL_NEGOTIATION`](/docs/ja/env-vars) を `auto` に設定し、チャネルサーバーが MCP プロトコルリビジョン 2026-07-28 をネゴシエートする場合、チャネルメッセージを配信できないため、Claude Code はそれをチャネルとして登録しません。変数を設定しないままにするか、`legacy` に設定して、stdio サーバーを以前のハンドシェイクに保ちます。

228 447 

229<Tip>448<Tip>

230 ヒント：449 ヒント：

231 450 

232 * `-s` または `--scope` フラグを使用して、設定が保存される場所を指定します：451 * `-s` または `--scope` フラグを使用して、設定が保存される場所を指定します。

233 * `local`（デフォルト）：現在のプロジェクトでのみ利用可能。古いバージョンではこのスコープを `project` と呼んでいました452 * `local`（デフォルト）: 現在のプロジェクトでのみ利用可能

234 * `project`：`.mcp.json` ファイルを通じてプロジェクト内のすべてのユーザーと共有453 * `project`: `.mcp.json` ファイルを通じてプロジェクト内のすべてのユーザーと共有

235 * `user`：すべてのプロジェクト全体で利用可能。古いバージョンではこのスコープを `global` と呼んでいました454 * `user`: すべてのプロジェクト全体で利用可能

236 * `-e` または `--env` フラグで環境変数を設定します（例：`-e KEY=value`）455 * `-e` または `--env` フラグで環境変数を設定します（例えば、`-e KEY=value`）

237 * `--transport` と `--header` フラグは `-t` と `-H` の短い形式も受け入れます456 * `--transport` と `--header` フラグは `-t` と `-H` 短形式も受け入れます

238 * `MCP_TIMEOUT` 環境変数を使用して MCP サーバーのスタートアップタイムアウトを設定します（例：`MCP_TIMEOUT=10000 claude` は 10 秒のタイムアウトを設定します）457 * `MCP_TIMEOUT` 環境変数を使用して MCP サーバー起動タイムアウトを設定します（例えば、`MCP_TIMEOUT=10000 claude` は 10 秒のタイムアウトを設定します）

239 * サーバーごとのツール実行タイムアウトを設定するには、そのサーバーの `.mcp.json` エントリにミリ秒単位で `timeout` フィールドを追加します。例えば、10 分の場合は `"timeout": 600000` です。これはそのサーバーのみの `MCP_TOOL_TIMEOUT` 環境変数をオーバーライドします458 * ミリ秒単位で `.mcp.json` エントリにそのサーバーの `timeout` フィールドを追加して、サーバーごとのツール実行タイムアウトを設定します。例えば `"timeout": 600000` は 10 分です。これは `MCP_TOOL_TIMEOUT` 環境変数をそのサーバーのみでオーバーライドします

240 * Claude Code は MCP ツール出力が 10,000 トークンを超えると警告を表示し、デフォルトで出力を 25,000 トークンに制限します。制限を増やすには、`MAX_MCP_OUTPUT_TOKENS` 環境変数を設定します（例：`MAX_MCP_OUTPUT_TOKENS=50000`）。警告しきい値は固定です。[MCP 出力制限と警告](#mcp-output-limits-and-warnings) を参照してください459 * Claude Code は MCP ツール出力が 10,000 トークンを超えるときに警告を表示し、デフォルトで出力を 25,000 トークンに制限します。制限を上げるには、`MAX_MCP_OUTPUT_TOKENS` 環境変数を設定します（例えば、`MAX_MCP_OUTPUT_TOKENS=50000`）。警告しきい値は固定です。[MCP 出力制限と警告](#mcp-output-limits-and-warnings) を参照してください

241 * `/mcp` を使用して、OAuth 2.0 認証が必要なリモートサーバーで認証します460 * `/mcp` を使用して、OAuth 2.0 認証が必要なリモートサーバーで認証します

242</Tip>461</Tip>

243 462 

244サーバーごとの `timeout` はツール呼び出しごとのハードウォールクロック制限であり、サーバーからの進捗通知はそれを延長しません。1000 未満の値は無視され、`MCP_TOOL_TIMEOUT` にフォールスルーするか、その変数が設定されていない場合は約 28 時間のデフォルトにフォールスルーします。HTTP、SSE、または [claude.ai コネクタ](/docs/ja/mcp#use-mcp-servers-from-claude-ai) サーバーの場合、サーバーの最初の応答バイトまでの各リクエストをカバーする、リクエストごとの 2 番目のタイマーもあります。このタイマーは、サーバーごとの `timeout` または `MCP_TOOL_TIMEOUT` を設定しない限り 60 秒です。どちらかを 60 秒以上に設定するとリクエストごとのタイマーがその値に上がり、より低い値ではそれを短縮しません。設定されていない `MCP_TOOL_TIMEOUT` の 28 時間のデフォルトはそれに供給されません。Stdio および WebSocket サーバーにはリクエストごとのタイマーがありません。v2.1.162 より前は、1000 未満の値は 1 秒に切り下げられていました。463サーバーごとの `timeout` はツール呼び出しごとのハードウォールクロック制限であり、サーバーからの進捗通知はそれを拡張しません。1000 未満の値は無視され、`MCP_TOOL_TIMEOUT` にフォールスルーするか、その変数が設定されていない場合は約 28 時間のデフォルトにフォールスルーします。HTTP、SSE、または [claude.ai コネクタ](/docs/ja/mcp#use-mcp-servers-from-claude-ai) サーバーの場合、サーバーの最初の応答バイトまでの各リクエストをカバーする 2 つ目の、リクエストごとのタイマーもあります。Claude Code はそのタイマーを 3 つの値の最大値に設定します。60 秒、サーバーに適用されるツールタイムアウト、`MCP_TIMEOUT`。設定されていない `MCP_TOOL_TIMEOUT` の 28 時間デフォルトはその比較に入らず、60 秒未満の値はタイマーを短縮しません。Stdio と WebSocket サーバーにはリクエストごとのタイマーがありません。

245 464 

246サーバーごとの `timeout` が少なくとも 1000 の場合、以下で説明するアイドルタイムアウトのフロアとしても機能します：Claude Code はそのサーバーのツール呼び出しをアイドルのために、サーバーごとの `timeout` より早く中止することはありません。Claude Code v2.1.203 以降が必要です。465少なくとも 1000 のサーバーごとの `timeout` は、以下で説明されるアイドルタイムアウトのフロアとしても機能します。Claude Code はそのサーバーのツール呼び出しをサーバーごとの `timeout` より早くアイドルのために中止しません。Claude Code v2.1.203 以降が必要です。

247 466 

248MCP サーバーへのツール呼び出しで、アイドルウィンドウ中に応答も進捗通知も送信されない場合、ウォールクロック制限を待つ代わりにエラーで中止されます。アイドルタイムアウトには Claude Code v2.1.187 以降が必要です。IDE サーバーと SDK インプロセスサーバーを除く、すべてのサーバータイプに適用されます。アイドルウィンドウは HTTP、SSE、WebSocket、および [claude.ai コネクタ](#use-mcp-servers-from-claude-ai) サーバーの場合は 5 分、stdio サーバーの場合は 30 分がデフォルトです。v2.1.203 より前は、stdio サーバーはアイドルタイムアウトの対象外でした。467応答も進捗通知も送信しない MCP サーバーへのツール呼び出しは、ウォールクロック制限を待つ代わりにエラーで中止されます。アイドルタイムアウトには Claude Code v2.1.187 以降が必要です。IDE サーバーと SDK インプロセスサーバーを除くすべてのサーバータイプに適用されます。アイドルウィンドウは HTTP、SSE、WebSocket、[claude.ai コネクタ](#use-mcp-servers-from-claude-ai) サーバーの場合は 5 分、stdio サーバーの場合は 30 分にデフォルト設定されます。v2.1.203 より前では、stdio サーバーはアイドルタイムアウトから除外されていました。

249 468 

250[`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/ja/env-vars) 環境変数をミリ秒単位で設定してアイドルウィンドウを変更するか、`0` に設定してチェックを無効にしてください。469[`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/ja/env-vars) 環境変数をミリ秒単位で設定してアイドルウィンドウを変更するか、`0` に設定してチェックを無効にしてください。

251 470 

471これらのタイムアウトは呼び出しがどのくらい実行できるかを制限し、常にどのくらいブロックするかではありません。2 分を超えて実行される主会話呼び出しは、最初にバックグラウンドタスクに移動します。[長いツール呼び出しの自動バックグラウンド化](#automatic-backgrounding-of-long-tool-calls) を参照してください。

472 

473<h3 id="automatic-backgrounding-of-long-tool-calls">

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

475</h3>

476 

477主会話の MCP ツール呼び出しが 2 分後も実行中の場合、セッションをブロックする代わりにバックグラウンドタスクに移動します。Claude はタスク ID をすぐに受け取り、作業を続け、結果は呼び出しが解決するときにタスク通知として到着します。自動バックグラウンド化には Claude Code v2.1.212 以降が必要です。

478 

479タスクは [`/tasks`](/docs/ja/commands#all-commands) に表示され、そこで停止することもでき、セッションを終了しても存続しません。呼び出しがバックグラウンドで実行されている間、呼び出しごとの制限は引き続き適用されます。サーバーごとの `timeout` または [`MCP_TOOL_TIMEOUT`](/docs/ja/env-vars) で設定されたウォールクロック制限、および [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/ja/env-vars) で設定されたアイドルタイムアウト。

480 

481[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/ja/env-vars) 環境変数をミリ秒単位で設定してしきい値を変更するか、`0` に設定して自動バックグラウンド化をオフにしてください。`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` を `1` に設定すると、それもオフになり、他のすべてのバックグラウンドタスク機能も同様です。

482 

483一部の呼び出しはバックグラウンドに移動しません。

484 

485* [サブエージェント](/docs/ja/sub-agents) からの呼び出し。Claude Code はメイン会話呼び出しのみをバックグラウンド化します

486* IDE サーバーへの呼び出し

487* [非対話モード](/docs/ja/headless) での呼び出し。ただし `CLAUDE_AUTO_BACKGROUND_TASKS` が `1` に設定されている場合を除きます。1 回限りの実行は結果が到着する前に終了する可能性があるため

488 

489開いている [エリシテーションダイアログ](#respond-to-mcp-elicitation-requests) を待つ呼び出しは、ダイアログが開いている間はバックグラウンド化されません。サーバーは遅いのではなく入力を待ってブロックされているため、Claude Code はダイアログが閉じるまで移動を延期します。

490 

252<h3 id="plugin-provided-mcp-servers">491<h3 id="plugin-provided-mcp-servers">

253 プラグイン提供の MCP サーバー492 プラグイン提供の MCP サーバー

254</h3>493</h3>

255 494 

256[プラグイン](/docs/ja/plugins) は MCP サーバーをバンドルでき、プラグインが有効になると自動的にツールと統合を提供します。プラグイン MCP サーバーはユーザーが設定したサーバーと同じように機能します。495[プラグイン](/docs/ja/plugins) は、プラグインを有効にするときにツールと統合を提供する MCP サーバーをバンドルできます。プラグイン MCP サーバーはユーザー設定サーバーと同じように機能します。

257 496 

258**プラグイン MCP サーバーの仕組み**：497**プラグイン MCP サーバーの動作方法**：

259 498 

260* プラグインはプラグインルートの `.mcp.json` または `plugin.json` 内でインラインで MCP サーバーを定義します499* プラグインはプラグインルートの `.mcp.json` または `plugin.json` にインラインで MCP サーバーを定義します

261* プラグインが有効になると、その MCP サーバーが自動的に起動します500* プラグインを有効にすると、Claude Code は自動的にその MCP サーバーを起動します

262* プラグイン MCP ツールは手動で設定された MCP ツールと一緒に表示されます501* Claude Code は手動で設定された MCP ツールと並んでプラグイン MCP ツールを提供します

263* プラグインサーバーはプラグインのインストールを通じて管理されます（`/mcp` コマンドではありません）502* プラグインサーバーを追加および削除するには、プラグインをインストールまたはアンインストールします。`/mcp` コマンドではなく。[インストールされたプラグインサーバーをオフに切り替える](#disable-a-server-without-removing-it) ことはできます。これにより、Claude Code がそれに接続するのを停止し、プラグインを削除することなく

264 503 

265**プラグイン MCP 設定の例**：504**プラグイン MCP 設定の例**：

266 505 

267プラグインルートの `.mcp.json` 内：506プラグインルートの `.mcp.json` で：

268 507 

269```json theme={null}508```json theme={null}

270{509{

280}519}

281```520```

282 521 

283または `plugin.json` 内でインライン：522または `plugin.json` にインラインで：

284 523 

285```json theme={null}524```json theme={null}

286{525{

296 535 

297**プラグイン MCP 機能**：536**プラグイン MCP 機能**：

298 537 

299* **自動ライフサイクル**：セッション起動時に、有効なプラグインのサーバーが自動的に接続されます。セッション中にプラグインを有効または無効にする場合は、`/reload-plugins` を実行して MCP サーバーを接続または切断してください538* **自動ライフサイクル**: サーバーはこれらのポイントで接続および切断されます。

300* **パス プレースホルダー**：`${CLAUDE_PLUGIN_ROOT}` はプラグインのインストールディレクトリに解決され、`${CLAUDE_PLUGIN_DATA}` はその [永続的な状態](/docs/ja/plugins-reference#persistent-data-directory) ディレクトリに解決され、`${CLAUDE_PROJECT_DIR}` は安定したプロジェクトルートに解決されます。置換は以下に適用されます：539 * セッション起動時、Claude Code は有効なプラグインのサーバーを自動的に接続します。`/mcp` では、以前使用したリモート（HTTP または SSE）プラグインサーバーは [`cached` ステータス](#server-status-detail) を代わりに表示できます。Claude Code は Claude が最初にそのツールの 1 つを呼び出すときに接続します

301 * `stdio` サーバー：`command`、`args`、`env`540 * セッション中にプラグインを有効または無効にする場合、Claude Code はその変更が適用されるときにその MCP サーバーを接続または切断します。[プラグイン変更を再起動なしで適用](/docs/ja/discover-plugins#apply-plugin-changes-without-restarting) はいつかを説明しています。対話的なターミナルのないセッションでは、`/reload-plugins` はプラグイン MCP サーバーを接続または切断しません。これらの変更は次のセッションで有効になります

302 * `http`、`sse`、`ws` サーバー：`url`、`headers`、`headersHelper`。v2.1.195 より前は、`headersHelper` はプレースホルダーをリテラル文字列として渡していました541 * リロードするとき、Claude Code は設定が変更されていないプラグインサーバーのライブ接続を保持し、Agent SDK から [セッションの MCP サーバーリストを置き換える](/docs/ja/agent-sdk/typescript#mcpsetserversresult) ときに同じことを行います。それらに名前を付けずに

303* **ユーザー環境アクセス**：手動で設定されたサーバーと同じ環境変数へのアクセス542 * v2.1.246 以降で [`/cd`](/docs/ja/permissions#move-the-session-to-another-directory) でセッションを移動するとき、Claude Code は新しいディレクトリの設定が有効にするプラグインのサーバーを接続し、有効でなくなったプラグインのサーバーを切断するため、移動後に `/reload-plugins` を実行する必要はありません

304* **複数のトランスポートタイプ**：stdio、SSE、HTTP、WebSocket トランスポートをサポート（トランスポートサポートはサーバーによって異なる場合があります）543 * [ウェブセッション](/docs/ja/claude-code-on-the-web) では、まだ接続されていないプラグインサーバーへの MCP 呼び出し（アイドルセッションが起動した直後など）は、サーバーをオンデマンドで開始し、接続を待ちます

305 544* **パスプレースホルダー**: `${CLAUDE_PLUGIN_ROOT}` はプラグインのインストールディレクトリに解決され、`${CLAUDE_PLUGIN_DATA}` はその [永続状態](/docs/ja/plugins-reference#persistent-data-directory) ディレクトリに解決され、`${CLAUDE_PROJECT_DIR}` は安定したプロジェクトルートに解決されます。置換は以下に適用されます。

306**プラグイン MCP サーバーの表示**：545 * `stdio` サーバー: `command`、`args`、`env`

546 * `http`、`sse`、`ws` サーバー: `url`、`headers`、`headersHelper`。v2.1.195 より前では、`headersHelper` はプレースホルダーをリテラル文字列として渡していました

547* **ユーザー環境アクセス**: 手動で設定されたサーバーと同じ環境変数へのアクセス

548* **複数のトランスポートタイプ**: stdio、SSE、HTTP、WebSocket トランスポートのサポート。ただし、トランスポートサポートはサーバーによって異なる場合があります

307 549 

308```bash theme={null}550プラグインサーバーは `/mcp` に表示され、プラグインから来ることを示すインジケータが付きます。

309# Claude Code 内で、プラグインのものを含むすべての MCP サーバーを表示

310/mcp

311```

312 

313プラグインサーバーはプラグインから来ていることを示すインジケータ付きでリストに表示されます。

314 551 

315**プラグイン MCP ツール名**：552**プラグイン MCP ツール名**：

316 553 

317プラグインでバンドルされた MCP サーバーからのツールには、呼び出し可能な名前にプラグイン名とサーバーキーの両方が含まれます。完全な形式は `mcp__plugin_<plugin-name>_<server-name>__<tool-name>` です。ここで、`A-Z`、`a-z`、`0-9`、`_`、`-` の外の任意の文字は `_` に置き換えられます。`my-plugin` という名前のプラグインでバンドルされた `database-tools` サーバーの場合、`query` ツールは以下のように呼び出し可能です：554プラグインにバンドルされた MCP サーバーからのツールは、呼び出し可能な名前にプラグイン名とサーバーキーの両方を含めます。完全な形式は `mcp__plugin_<plugin-name>_<server-name>__<tool-name>` です。`A-Z`、`a-z`、`0-9`、`_`、`-` の外の任意の文字は `_` に置き換えられます。`my-plugin` という名前のプラグインにバンドルされた `database-tools` サーバーの場合、`query` ツールは以下のように呼び出し可能です。

318 555 

319```556```

320mcp__plugin_my-plugin_database-tools__query557mcp__plugin_my-plugin_database-tools__query

321```558```

322 559 

323[権限ルール](/docs/ja/permissions)、スキルの `allowed-tools` リスト、[サブエージェントの `tools` フィールド](/docs/ja/sub-agents#available-tools)、または [hook マッチャー](/docs/ja/hooks#match-mcp-tools) でツールを参照する場合は、この完全な名前を使用してください。`mcp__database-tools__.*` などのベアサーバーキーに対して記述された hook マッチャーは、プラグインでバンドルされたサーバーに対しては発火しません。560[権限ルール](/docs/ja/permissions)、スキルの `allowed-tools` リスト、[サブエージェントの `tools` フィールド](/docs/ja/sub-agents#available-tools)、または [フック マッチャー](/docs/ja/hooks#match-mcp-tools) でツールを参照するときに、この完全な名前を使用してください。裸のサーバーキー（`mcp__database-tools__.*` など）に対して書かれたフック マッチャーは、プラグインにバンドルされたサーバーに対して発火しません。

324 

325サーバー自体は、`plugin:<plugin-name>:<server-name>`（例：`plugin:my-plugin:database-tools`）などのスコープ付き名前で登録されます。設定されたサーバー名が予想される場所（例：[`mcp_tool` hook の `server` フィールド](/docs/ja/hooks#mcp-tool-hook-fields)）でその名前を使用してください。

326 

327**プラグイン MCP サーバーの利点**：

328 561 

329* **バンドル配布**：ツールとサーバーが一緒にパッケージ化されます562サーバー自体は `plugin:<plugin-name>:<server-name>`（`plugin:my-plugin:database-tools` など）のスコープ付き名前で登録されます。設定されたサーバー名が予想される場所（[`mcp_tool` フックの `server` フィールド](/docs/ja/hooks#mcp-tool-hook-fields) など）でその名前を使用してください。

330* **自動セットアップ**：手動の MCP 設定は不要です

331* **チーム一貫性**：プラグインがインストールされると、すべてのユーザーが同じツールを取得します

332 563 

333プラグインで MCP サーバーをバンドルする詳細については、[プラグインコンポーネントリファレンス](/docs/ja/plugins-reference#mcp-servers) を参照してください。564プラグインで MCP サーバーをバンドルする詳細については、[プラグインコンポーネントリファレンス](/docs/ja/plugins-reference#mcp-servers) を参照してください。

334 565 

336 MCP インストールスコープ567 MCP インストールスコープ

337</h2>568</h2>

338 569 

339MCP サーバーは 3 つのスコープで設定できます。選択するスコープは、サーバーがロードされるプロジェクトと、設定がチームと共有されるかどうかを制御します。管理者は、[マネージド設定](#managed-mcp-configuration)を通じてエンタープライズレベルでサーバーをデプロイすることもできます。570MCP サーバーは 3 つのスコープで設定できます。選択するスコープは、サーバーがロードされるプロジェクトと、設定がチームと共有されるかどうかを制御します。管理者は、[マネージド設定](#managed-mcp-configuration)を通じてすべてのユーザーに対してサーバーをデプロイまたは提供することもできます。

340 571 

341| スコープ | ロード対象 | チームと共有 | 保存場所 |572| スコープ | ロード対象 | チームと共有 | 保存場所 |

342| ------------------------ | ----------- | ------------ | ---------------------- |573| ------------------------ | ----------- | ------------ | ---------------------- |

351ローカルスコープはデフォルトです。ローカルスコープのサーバーは、追加したプロジェクトでのみロードされ、あなたにプライベートなままです。Claude Code は `~/.claude.json` のそのプロジェクトのパスの下に保存するため、同じサーバーは他のプロジェクトに表示されません。個人開発サーバー、実験的な設定、またはバージョン管理に含めたくない認証情報を持つサーバーにはローカルスコープを使用してください。582ローカルスコープはデフォルトです。ローカルスコープのサーバーは、追加したプロジェクトでのみロードされ、あなたにプライベートなままです。Claude Code は `~/.claude.json` のそのプロジェクトのパスの下に保存するため、同じサーバーは他のプロジェクトに表示されません。個人開発サーバー、実験的な設定、またはバージョン管理に含めたくない認証情報を持つサーバーにはローカルスコープを使用してください。

352 583 

353<Note>584<Note>

354 MCP サーバーの「ローカルスコープ」という用語は、一般的なローカル設定とは異なります。MCP ローカルスコープのサーバーは `~/.claude.json`（ホームディレクトリ）に保存されますが、一般的なローカル設定は `.claude/settings.local.json`（プロジェクトディレクトリ内）を使用します。設定ファイルの場所の詳細については、[設定](/docs/ja/settings#settings-files)を参照してください。585 MCP サーバーの「ローカルスコープ」という用語は、一般的なローカル設定とは異なります。MCP ローカルスコープのサーバーは `~/.claude.json`（ホームディレクトリ）に保存されますが、一般的なローカル設定は `.claude/settings.local.json`（プロジェクトディレクトリ内）を使用します。設定ファイルの場所の詳細については、[設定](/docs/ja/settings#where-settings-live)を参照してください。

355</Note>586</Note>

356 587 

357```bash theme={null}588```bash theme={null}

383 プロジェクトスコープ614 プロジェクトスコープ

384</h3>615</h3>

385 616 

386プロジェクトスコープのサーバーは、プロジェクトのルートディレクトリの `.mcp.json` ファイルに設定を保存することで、チーム間のコラボレーションを可能にします。このファイルはバージョン管理にチェックインするように設計されており、すべてのチームメンバーが同じ MCP ツールとサービスにアクセスできることを保証します。プロジェクトスコープのサーバーを追加すると、Claude Code は自動的にこのファイルを作成または更新して、適切な設定構造を使用します。617プロジェクトスコープのサーバーは、プロジェクトのルートディレクトリの `.mcp.json` ファイルに設定を保存することで、チーム間のコラボレーションを可能にします。プロジェクトスコープのサーバーを追加すると、Claude Code は自動的にこのファイルを作成または更新して、適切な設定構造を使用します。`.mcp.json` をバージョン管理にチェックインして、チームのすべてのメンバーが同じ MCP ツールとサービスを取得するようにしてください。

387 618 

388```bash theme={null}619```bash theme={null}

389# プロジェクトスコープのサーバーを追加する620# プロジェクトスコープのサーバーを追加する

390claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp621claude mcp add --transport http shared-server --scope project https://example.com/mcp

391```622```

392 623 

393結果の `.mcp.json` ファイルは標準化された形式に従います：624結果の `.mcp.json` ファイルは標準化された形式に従います：

396{627{

397 "mcpServers": {628 "mcpServers": {

398 "shared-server": {629 "shared-server": {

399 "command": "/path/to/server",630 "type": "http",

400 "args": [],631 "url": "https://example.com/mcp"

401 "env": {}

402 }632 }

403 }633 }

404}634}

405```635```

406 636 

407セキュリティ上の理由から、Claude Code は `.mcp.json` ファイルからプロジェクトスコープのサーバーを使用する前に承認を求めます。これらの承認選択をリセットする必要がある場合は、`claude mcp reset-project-choices` コマンドを使用してください。637セキュリティ上の理由から、Claude Code はインタラクティブセッションで `.mcp.json` ファイルからプロジェクトスコープのサーバーを使用する前に承認を求めます。これらの承認選択をリセットするには、`claude mcp reset-project-choices` を実行してください。

638 

639`claude -p` 実行、[Agent SDK](/docs/ja/headless)セッション、および[クラウドセッション](/docs/ja/claude-code-on-the-web)では、Claude Code はそのプロンプトを表示できません。プロジェクトスコープのサーバーを確認なしでロードします。Claude Code はまた、ユーザー設定またはマネージド設定で [`skipDangerousModePermissionPrompt`](/docs/ja/settings-reference#skipdangerousmodepermissionprompt) が設定された `bypassPermissions` モードで開始したセッションではプロンプトをスキップします。とにかくサーバーを除外するには：

640 

641* [`disabledMcpjsonServers`](/docs/ja/settings-reference#disabledmcpjsonservers)に追加します。これはすべての権限モードでそれをブロックします。

642* [`--setting-sources`](/docs/ja/cli-reference#cli-flags)またはSDKの `settingSources` オプションでプロジェクト設定全体を除外します。

643* [`--strict-mcp-config`](/docs/ja/cli-reference#cli-flags)でセッションを開始します。Claude Code は `--mcp-config` で渡した MCP サーバーのみを使用します。Claude Code がロードしていないプロジェクトスコープのサーバーの承認プロンプトをスキップするには、Claude Code v2.1.246 以降が必要です。v2.1.246 より前では、厳密なセッションでもそれらの承認を待機していたため、バックグラウンドセッションは起動時に待機していました。マネージド MCP ファイルの下でフラグが何をするかについては、[マネージド mcp.json での排他的制御](/docs/ja/managed-mcp#exclusive-control-with-managed-mcp-json)を参照してください。

644 

645[プロジェクトサーバーの承認とワークスペーストラスト](#project-server-approvals-and-workspace-trust)は、リポジトリにコミットされた承認がワークスペーストラストとどのように相互作用するかについて説明しています。

408 646 

409<h3 id="user-scope">647<h3 id="user-scope">

410 ユーザースコープ648 ユーザースコープ

421 スコープの階層と優先順位659 スコープの階層と優先順位

422</h3>660</h3>

423 661 

424同じサーバーが複数の場所で定義されている場合、Claude Code はそれに 1 回接続し、最も優先度の高いソースからの定義を使用します。その定義全体が使用され、フィールドはスコープ全体でマージされません。662同じサーバーが複数の場所で定義されている場合、Claude Code はそれに 1 回接続し、最も優先度の高いソースからの定義を使用します。そのソースからのサーバーエントリ全体が使用されます。フィールドはスコープ全体でマージされません。

425 663 

4261. ローカルスコープ6641. ローカルスコープ

4272. プロジェクトスコープ6652. プロジェクトスコープ

431 669 

4323 つのスコープは名前で重複を照合します。プラグインとコネクタはエンドポイントで照合するため、上記のサーバーと同じ URL またはコマンドを指すものは重複として扱われます。6703 つのスコープは名前で重複を照合します。プラグインとコネクタはエンドポイントで照合するため、上記のサーバーと同じ URL またはコマンドを指すものは重複として扱われます。

433 671 

672組織が [`managedMcpServers`](/docs/ja/managed-mcp#provide-servers-through-managed-settings)マネージド設定を通じて提供するサーバーは、これらすべての上にランクされるため、それらの 1 つがそれを複製する場合、Claude Code は組織の定義に接続します。Claude Code v2.1.259 以降が必要です。

673 

674[Desktop アプリの Code タブ](/docs/ja/desktop#mcp-servers-from-the-claude-desktop-chat-app)でローカルセッションを開く場合、`~/.claude.json`（ユーザースコープ）のトップレベルと `.mcp.json` に同じ stdio サーバー名がある場合、Code タブは `~/.claude.json` 定義を使用します。

675 

434<h3 id="environment-variable-expansion-in-mcp-json">676<h3 id="environment-variable-expansion-in-mcp-json">

435 `.mcp.json` での環境変数の展開677 `.mcp.json` での環境変数の展開

436</h3>678</h3>

467}709}

468```710```

469 711 

470参照される環境変数が設定されておらず、デフォルト値がない場合、Claude Code はリテラルな `${VAR}` テキストを値に残し、そのサーバーに対して欠落変数の警告を報告します。設定はまだロードされるため、変数を設定するか、`:-default` フォールバックを追加して、サーバーが意図した値で起動するようにしてください。712参照される環境変数が設定されておらず、デフォルト値がない場合、設定はまだロードされます。Claude Code はそのサーバーに対して `claude mcp list` 出力で欠落変数の警告を報告し、展開されていない `${VAR}` テキストをそのまま使用します。変数を設定するか、`:-default` フォールバックを追加して、サーバーが意図した値で起動するようにしてください。

471 713 

472<h2 id="practical-examples">714<h2 id="practical-examples">

473 実践的な例715 実践的な例

474</h2>716</h2>

475 717 

476<h3 id="example-monitor-errors-with-sentry">

477 例：Sentry でエラーを監視する

478</h3>

479 

480```bash theme={null}

481claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

482```

483 

484Sentry アカウントで認証します：

485 

486```text theme={null}

487/mcp

488```

489 

490その後、本番環境の問題をデバッグします：

491 

492```text theme={null}

493過去 24 時間で最も一般的なエラーは何ですか？

494```

495 

496```text theme={null}

497エラー ID abc123 のスタックトレースを表示してください

498```

499 

500```text theme={null}

501どのデプロイメントがこれらの新しいエラーを導入しましたか？

502```

503 

504<h3 id="example-connect-to-github-for-code-reviews">718<h3 id="example-connect-to-github-for-code-reviews">

505 例：コードレビューのために GitHub に接続する719 例：コードレビューのために GitHub に接続する

506</h3>720</h3>

512 --header "Authorization: Bearer YOUR_GITHUB_PAT"726 --header "Authorization: Bearer YOUR_GITHUB_PAT"

513```727```

514 728 

729`YOUR_GITHUB_PAT` を個人アクセストークンに置き換えてください。`claude mcp add` コマンドは認証情報を検証せずに設定を保存するため、ここではプレースホルダー値が受け入れられますが、サーバーは後で接続に失敗します。接続を確認するには、`/mcp` を実行し、サーバーが `connected` と表示されていることを確認してください。認証情報が不正なサーバーは `failed` と表示され、失敗の詳細には、サーバーが返した HTTP ステータス（401 など）が含まれます。

730 

515その後、GitHub で作業します：731その後、GitHub で作業します：

516 732 

517```text theme={null}733```text wrap theme={null}

518PR #456 をレビューして改善を提案してください734PR #456 をレビューして改善を提案してください

519```735```

520 736 

521```text theme={null}737```text wrap theme={null}

522見つけたバグの新しい課題を作成してください738見つけたバグの新しい課題を作成してください

523```739```

524 740 

525```text theme={null}741```text wrap theme={null}

526自分に割り当てられているすべてのオープン PR を表示してください742自分に割り当てられているすべてのオープン PR を表示してください

527```743```

528 744 

530 例：PostgreSQL データベースをクエリする746 例：PostgreSQL データベースをクエリする

531</h3>747</h3>

532 748 

749[DBHub](https://github.com/bytebase/dbhub)（`@bytebase/dbhub` パッケージ）は、`--dsn` で渡す接続文字列を通じて Claude をリレーショナルデータベースに接続する MCP サーバーです。Claude が実行するクエリがデータを変更できないように、接続文字列で読み取り専用データベースユーザーを使用してください：

750 

533```bash theme={null}751```bash theme={null}

534claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \752claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \

535 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"753 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

536```754```

537 755 

756サーバーが起動することを確認するには、`/mcp` を実行し、`db` が `connected` と表示されていることを確認してください。

757 

538その後、データベースを自然に照会します：758その後、データベースを自然に照会します：

539 759 

540```text theme={null}760```text wrap theme={null}

541今月の総収益はいくらですか？761今月の総収益はいくらですか？

542```762```

543 763 

544```text theme={null}764```text wrap theme={null}

545orders テーブルのスキーマを表示してください765orders テーブルのスキーマを表示してください

546```766```

547 767 

548```text theme={null}768```text wrap theme={null}

549過去 90 日間に購入していない顧客を検索してください769過去 90 日間に購入していない顧客を検索してください

550```770```

551 771 

555 775 

556多くのクラウドベースの MCP サーバーは認証が必要です。Claude Code は安全な接続のために OAuth 2.0 をサポートしています。776多くのクラウドベースの MCP サーバーは認証が必要です。Claude Code は安全な接続のために OAuth 2.0 をサポートしています。

557 777 

558Claude Code は、サーバーが `401 Unauthorized` または `403 Forbidden` で応答するときに、リモートサーバーが認証を必要とするとマークします。どちらのステータスコードでも、サーバーは `/mcp` でフラグが立てられ、OAuth フローを完了できます。778Claude Code は、サーバーが `401 Unauthorized` または `403 Forbidden` で応答するとき、リモートサーバーが認証を必要としていることをマークします。Claude Code が表示する内容はサーバーによって異なります。

779 

780* サインインしていないサーバーの場合、どちらのステータスコードでも `/mcp` でフラグが立てられるため、OAuth フローを完了できます。

781* [claude.ai コネクタ](#use-mcp-servers-from-claude-ai)の場合、claude.ai がセッショントークンを拒否することによる `401` はコネクタにフラグを立てません。コネクタを再認可してもログインを修正できないためです。Claude Code は代わりに[セッショントークン拒否状態](/docs/ja/errors#claude-ai-rejected-the-session-token)を表示します。

782* `Authorization` ヘッダーを設定したサーバーの場合、`headers` または [`headersHelper`](#use-dynamic-headers-for-custom-authentication) を通じて、接続中の `401` または `403` はサーバーにフラグを立てません。修正する認証情報は設定した認証情報だからです。Claude Code は代わりに接続が失敗したことを報告します。

783* [クラウドセッションに配信されたコネクタ](#how-connectors-reach-claude-code)の場合、Claude Code はサインインフローを実行しません。セッションのプロキシが claude.ai で付与した認可を使用してコネクタに認証するためです。そこでコネクタが再度認可が必要な場合、セッションからではなく [claude.ai/customize/connectors](https://claude.ai/customize/connectors) で再接続してください。

559 784 

560既にサインインしている OAuth サーバーへのリクエストが `401 Unauthorized` を返す場合、Claude Code は保存されたトークンをリフレッシュし、再接続して、リクエストを 1 回再試行します。その再試行も失敗した場合にのみ、サーバーを `/mcp` でフラグが立てられます。v2.1.206 より前は、ネットワークエラーなどの一時的な理由でトークンリフレッシュが失敗した場合、リフレッシュトークンがまだ有効であっても、OAuth サーバーはセッションの残りの間、認証が必要とマークされていました。785既にサインインした OAuth サーバーへのリクエストが `401 Unauthorized` を返すとき、Claude Code は保存されたトークンをリフレッシュし、再接続して、リクエストを 1 回再試行します。その再試行も失敗した場合にのみ、`/mcp` でサーバーにフラグを立てます。v2.1.206 より前は、ネットワークエラーなどの一時的な理由でトークンリフレッシュが失敗した場合、リフレッシュトークンがまだ有効であっても、OAuth サーバーは残りのセッション中、認証が必要としてフラグが立てられていました。

561 786 

562v2.1.195 以降、トークンの更新がサーバーが保存されたリフレッシュトークンを拒否したために失敗する場合、Claude Code は `/mcp` を指す通知をすぐに表示します。接続されたサーバーのメニューはそこで「Re-authenticate」を提供するため、次のツール呼び出しが失敗する前に再度サインインできます。787サーバーが保存されたリフレッシュトークンを拒否するとき、Claude Code は直ちに `/mcp` を指す通知を表示します。`/mcp` を開き、サーバーで **Re-authenticate** を選択して、次のツール呼び出しが失敗する前に再度サインインしてください。

563 788 

564認可サーバーを指す `WWW-Authenticate` ヘッダーを返すカスタムサーバーは、他のリモートサーバーと同じ自動検出を取得します。789`WWW-Authenticate` ヘッダーを返すカスタムサーバーは、その認可サーバーを指し、他のリモートサーバーと同じ自動検出を取得します。

565 790 

566v2.1.193 以降、Claude Code は 1 つ以上の設定されたサーバーが認証を必要とする場合、スタートアップ通知も表示するため、どのサーバーがサインインを必要とするかを発見するために `/mcp` を開く必要がありません。791Claude Code は、1 つ以上の設定されたサーバーが認証を必要とするときにスタートアップ通知も表示するため、`/mcp` を開いて認証が必要なサーバーを検出する必要がありません。この通知には Claude Code v2.1.193 以降が必要です。Claude Code からサインインできるサーバーのみをカウントします。v2.1.218 より前は、claude.ai で接続されていない [claude.ai コネクタ](#use-mcp-servers-from-claude-ai)もカウントされていました。これらは claude.ai 設定からのみ接続できます。

567 792 

568非対話型モードでは `/mcp` パネルがないため、Claude Code は OAuth フローを実行できません。v2.1.196 以降、設定されたサーバーが `claude -p` または [ツール検索](#scale-with-mcp-tool-search) が有効になっている Agent SDK 実行中に認証を必要とする場合（これはデフォルトです）、Claude Code は Claude にサーバーのツールが認可されるまで利用できないことを伝えます。Claude はサーバーが設定されていないかのように応答するのではなく、サインインが必要なサーバーに名前を付けることができます。対話型セッションから `/mcp` または `claude mcp login <name>` でサインインを完了してください。793非対話モードでは `/mcp` パネルがないため、Claude Code は OAuth フローを実行できません。v2.1.196 以降、[ツール検索](#scale-with-mcp-tool-search)が有効な（デフォルト）`claude -p` または Agent SDK 実行中に設定されたサーバーが認証を必要とするとき、Claude Code はサーバーのツールが認可されるまで利用できないことを Claude に伝えます。Claude はサーバーが設定されていないかのように応答する代わりに、サインインが必要なサーバーに名前を付けることができます。対話セッションから `/mcp` または `claude mcp login <name>` でサインインを完了してください。

569 794 

570`headers.Authorization` をサーバー用に設定し、サーバーがそのヘッダーを拒否する場合、Claude Code は OAuth にフォールバックするのではなく、接続が失敗したと報告します。トークンが MCP エンドポイント用に有効であることを確認するか、OAuth フローを使用するためにヘッダーを削除してください。795サーバーに `headers.Authorization` を設定し、サーバーがそのヘッダーを拒否する場合、Claude Code は OAuth にフォールバックする代わりに接続が失敗したことを報告します。トークンが MCP エンドポイントに対して有効であることを確認するか、ヘッダーを削除して OAuth フローを使用してください。

571 796 

572<Steps>797<Steps>

573 <Step title="認証が必要なサーバーを追加する">798 <Step title="認証が必要なサーバーを追加する">

574 例：799 [MCP クイックスタート](/docs/ja/mcp-quickstart#connect-a-server-that-requires-sign-in)で既に `sentry` サーバーを追加した場合、このステップをスキップしてください。同じサーバー名で同じスコープで `claude mcp add` を再度実行すると、`MCP server sentry already exists in local config` で失敗します。それ以外の場合は、以下を実行してください。

575 800 

576 ```bash theme={null}801 ```bash theme={null}

577 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp802 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

579 </Step>804 </Step>

580 805 

581 <Step title="Claude Code 内で /mcp コマンドを使用する">806 <Step title="Claude Code 内で /mcp コマンドを使用する">

582 Claude Code で、コマンドを使用します：807 Claude Code で、以下のコマンドを使用します。

583 808 

584 ```text theme={null}809 ```text wrap theme={null}

585 /mcp810 /mcp

586 ```811 ```

587 812 

588 その後、ブラウザでログインするための手順に従ってください。813 その後、ブラウザーのステップに従ってログインしてください。

589 </Step>814 </Step>

590</Steps>815</Steps>

591 816 

592<Tip>817<Tip>

593 ヒント：818 ヒント：

594 819 

595 * 認証トークンは安全に保存され、自動的に更新されます820 * 認証トークンは安全に保存され、自動的にリフレッシュされます

596 * `/mcp` メニューで「Clear authentication」を使用してアクセスを取り消します821 * `/mcp` メニューの「Clear authentication」を使用してアクセスを取り消します

597 * ブラウザが自動的に開かない場合は、提供された URL をコピーして手動で開いてください822 * ブラウザーが自動的に開かない場合は、提供された URL をコピーして手動で開いてください

598 * ブラウザのリダイレクトが認証後に接続エラーで失敗する場合は、ブラウザのアドレスバーから完全なコールバック URL を Claude Code に表示される URL プロンプトに貼り付けてください823 * 認証後、ブラウザーリダイレクトが接続エラーで失敗する場合は、ブラウザーのアドレスバーから完全なコールバック URL を貼り付けて、Claude Code に表示される URL プロンプトに入力してください

599 * OAuth 認証は HTTP サーバーで機能します824 * OAuth 認証は HTTP サーバーで機能します

600</Tip>825</Tip>

601 826 

603 コマンドラインから認証する828 コマンドラインから認証する

604</h3>829</h3>

605 830 

606v2.1.186 以降、`claude mcp login <name>` はシェルから直接設定されたサーバーの OAuth フローを実行するため、セッション内で `/mcp` パネルを開く必要がありません。831v2.1.186 から、`claude mcp login <name>` は設定されたサーバーの OAuth フローをシェルから直接実行するため、セッション内の `/mcp` パネルを開く必要がありません。

607 832 

608```bash theme={null}833```bash theme={null}

609claude mcp login sentry834claude mcp login sentry

611 836 

612後で保存された認証情報をクリアするには、`claude mcp logout <name>` を実行してください。837後で保存された認証情報をクリアするには、`claude mcp logout <name>` を実行してください。

613 838 

614v2.1.191 以降、このコマンドは SSH セッション中やディスプレイサーバーのない Linux など、ローカルブラウザが利用できない場合を検出し、ブラウザを開こうとするのではなく認可 URL を出力します。ローカルマシンで URL を開き、ブラウザのアドレスバーから完全なリダイレクト URL をプロンプトに貼り付けます。コマンドは貼り付けステップのためにインタラクティブなターミナルが必要なため、`ssh -t` で接続してください。ローカルブラウザが検出された場合でも URL プロンプトを強制するには、`--no-browser` を渡してください。839v2.1.191 以降、このコマンドは SSH セッション中やディスプレイサーバーのない Linux など、ローカルブラウザーが利用できない場合を検出し、ブラウザーを開こうとする代わりに認可 URL を出力します。ローカルマシンで URL を開き、ブラウザーのアドレスバーから完全なリダイレクト URL をプロンプトに貼り付けてください。このコマンドは貼り付けステップのために対話型ターミナルが必要なため、`ssh -t` で接続してください。ローカルブラウザーが検出された場合でも URL プロンプトを強制するには、`--no-browser` を渡してください。

615 840 

616```bash theme={null}841```bash theme={null}

617claude mcp login sentry --no-browser842claude mcp login sentry --no-browser

621 固定 OAuth コールバックポートを使用する846 固定 OAuth コールバックポートを使用する

622</h3>847</h3>

623 848 

624一部の MCP サーバーは、事前に登録された特定のリダイレクト URI が必要です。デフォルトでは、Claude Code は OAuth コールバック用にランダムに利用可能なポートを選択します。`--callback-port` を使用してポートを固定し、`http://localhost:PORT/callback` の形式の事前登録されたリダイレクト URI と一致させます。849一部の MCP サーバーは、事前に登録された特定のリダイレクト URI が必要です。デフォルトでは、Claude Code は OAuth コールバック用にランダムに利用可能なポートを選択します。`--callback-port` を使用してポートを固定し、`http://localhost:PORT/callback` 形式の事前登録されたリダイレクト URI と一致させてください。Claude Code v2.1.229 でのサインインがリダイレクト URI の不一致で失敗する場合は、[事前設定された OAuth 認証情報を使用する](#use-pre-configured-oauth-credentials)の下のバージョンノートを参照してください。

625 850 

626`--callback-port` を単独で使用できます（動的クライアント登録を使用）、または `--client-id` と一緒に使用できます（事前設定された認証情報を使用）。851`--callback-port` は単独で（動的クライアント登録を使用）または `--client-id` と一緒に（事前設定された認証情報を使用）使用できます。

627 852 

628```bash theme={null}853```bash theme={null}

629# 動的クライアント登録を使用した固定コールバックポート854# 動的クライアント登録を使用した固定コールバックポート

636 事前設定された OAuth 認証情報を使用する861 事前設定された OAuth 認証情報を使用する

637</h3>862</h3>

638 863 

639一部の MCP サーバーは、Dynamic Client Registration を通じた自動 OAuth セットアップをサポートしていません。「Incompatible auth server: does not support dynamic client registration」のようなエラーが表示される場合、サーバーは事前設定された認証情報が必要です。Claude Code は Client ID Metadata Document（CIMD）を使用するサーバーもサポートしており、これらを自動的に検出します。自動検出に失敗した場合は、まずサーバーの開発者ポータルを通じて OAuth アプリを登録し、サーバーを追加するときに認証情報を提供してください。864一部の MCP サーバーは、動的クライアント登録による自動 OAuth セットアップをサポートしていません。「Incompatible auth server: does not support dynamic client registration」のようなエラーが表示される場合、サーバーは事前設定された認証情報が必要です。Claude Code は、動的クライアント登録の代わりにクライアント ID メタデータドキュメント（CIMD）を使用するサーバーもサポートし、これらを自動的に検出します。自動検出が失敗する場合は、サーバーの開発者ポータルを通じて OAuth アプリを登録してから、サーバーを追加するときに認証情報を提供してください。

640 865 

641<Steps>866<Steps>

642 <Step title="サーバーで OAuth アプリを登録する">867 <Step title="サーバーで OAuth アプリを登録する">

643 サーバーの開発者ポータルを通じてアプリを作成し、クライアント ID とクライアントシークレットをメモしてください。868 サーバーの開発者ポータルを通じてアプリを作成し、クライアント ID とクライアントシークレットをメモしてください。

644 869 

645 多くのサーバーはリダイレクト URI も必要とします。その場合は、ポートを選択し、`http://localhost:PORT/callback` の形式でリダイレクト URI を登録してください。次のステップで `--callback-port` と同じポートを使用してください。870 多くのサーバーはリダイレクト URI も必要とします。その場合は、ポートを選択し、`http://localhost:PORT/callback` 形式でリダイレクト URI を登録してください。次のステップで `--callback-port` と同じポートを使用してください。

871 

872 v2.1.229 では、Claude Code は代わりに `http://127.0.0.1:PORT/callback` を送信していました。登録されたリダイレクト URI と完全に一致するサーバーは、リダイレクト URI の不一致でサインインを拒否していました。Claude Code v2.1.231 は `localhost` 形式を復元しました。v2.1.229 で復旧するには、Claude Code をアップグレードするか、一時的にサーバーの登録されたリダイレクト URI に `http://127.0.0.1:PORT/callback` 形式を追加してください。

646 </Step>873 </Step>

647 874 

648 <Step title="認証情報を使用してサーバーを追加する">875 <Step title="認証情報を使用してサーバーを追加する">

649 次のいずれかの方法を選択してください。`--callback-port` に使用されるポートは、利用可能な任意のポートにすることができます。前のステップで登録したリダイレクト URI と一致する必要があります。876 以下のいずれかの方法を選択してください。`--callback-port` に使用されるポートは、利用可能な任意のポートにできます。前のステップで登録したリダイレクト URI と一致する必要があります。

650 877 

651 <Tabs>878 <Tabs>

652 <Tab title="claude mcp add">879 <Tab title="claude mcp add">

653 `--client-id` を使用してアプリのクライアント ID を渡します。`--client-secret` フラグはマスクされた入力でシークレットを求めます：880 `--client-id` を使用してアプリのクライアント ID を渡します。`--client-secret` フラグはマスクされた入力でシークレットをプロンプトします。

654 881 

655 ```bash theme={null}882 ```bash theme={null}

656 claude mcp add --transport http \883 claude mcp add --transport http \

660 </Tab>887 </Tab>

661 888 

662 <Tab title="claude mcp add-json">889 <Tab title="claude mcp add-json">

663 JSON 設定に `oauth` オブジェクトを含め、`--client-secret` を別のフラグとして渡します：890 JSON 設定に `oauth` オブジェクトを含め、`--client-secret` を別のフラグとして渡します。

664 891 

665 ```bash theme={null}892 ```bash theme={null}

666 claude mcp add-json my-server \893 claude mcp add-json my-server \

670 </Tab>897 </Tab>

671 898 

672 <Tab title="claude mcp add-json（コールバックポートのみ）">899 <Tab title="claude mcp add-json（コールバックポートのみ）">

673 動的クライアント登録を使用しながらポートを固定するには、クライアント ID なしで `--callback-port` を使用します：900 動的クライアント登録を使用しながらポートを固定するには、クライアント ID なしで `--callback-port` を使用します。

674 901 

675 ```bash theme={null}902 ```bash theme={null}

676 claude mcp add-json my-server \903 claude mcp add-json my-server \

678 ```905 ```

679 </Tab>906 </Tab>

680 907 

681 <Tab title="CI / env var">908 <Tab title="CI / 環境変数">

682 環境変数を通じてシークレットを設定して、対話的なプロンプトをスキップします：909 環境変数を通じてシークレットを設定して、対話型プロンプトをスキップします。

683 910 

684 ```bash theme={null}911 ```bash theme={null}

685 MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \912 MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \

691 </Step>918 </Step>

692 919 

693 <Step title="Claude Code で認証する">920 <Step title="Claude Code で認証する">

694 Claude Code で `/mcp` を実行し、ブラウザのログインフローに従ってください。921 Claude Code で `/mcp` を実行し、ブラウザーログインフローに従ってください。

695 </Step>922 </Step>

696</Steps>923</Steps>

697 924 

698<Tip>925<Tip>

699 ヒント：926 ヒント：

700 927 

701 * クライアントシークレットはシステムキーチェーン（macOS）または認証情報ファイルに安全に保存され、設定には保存されません928 * クライアントシークレットは、設定ではなく、システムキーチェーン（macOS）または認証情報ファイルに安全に保存されます

702 * サーバーがシークレットなしのパブリック OAuth クライアントを使用する場合は、`--client-secret` なしで `--client-id` のみを使用してください929 * クライアントシークレットはサーバーを追加するときにのみ設定できます。`claude mcp login` または `/mcp` から認証するとき、Claude Code は保存されたシークレットを使用し、プロンプトを表示したり `MCP_CLIENT_SECRET` を読み込んだりしません

703 * `--callback-port` は `--client-id` の有無にかかわらず使用できます930 * 後でシークレットを追加または変更するには、`claude mcp remove <name>` でサーバーを削除してから、`--client-secret` と同じ `--scope` で再度追加してください

704 * これらのフラグは HTTP および SSE トランスポートにのみ適用されます。stdio サーバーには影響しません931 * サーバーがシークレットのないパブリック OAuth クライアントを使用する場合は、`--client-secret` なしで `--client-id` のみを使用してください

705 * `claude mcp get <name>` を使用して、OAuth 認証情報がサーバーに設定されていることを確認してください932 * これらのフラグは HTTP および SSE トランスポートにのみ適用されます。stdio サーバーには効果がありません

933 * `claude mcp get <name>` を使用して、OAuth 認証情報がサーバーに対して設定されていることを確認してください

706</Tip>934</Tip>

707 935 

708<h3 id="override-oauth-metadata-discovery">936<h3 id="override-oauth-metadata-discovery">

709 OAuth メタデータ検出をオーバーライドする937 OAuth メタデータ検出をオーバーライドする

710</h3>938</h3>

711 939 

712Claude Code を特定の OAuth 認可サーバーメタデータ URL に指定して、デフォルトの検出チェーンをバイパスします。MCP サーバーの標準エンドポイントがエラーになる場合、または内部プロキシを通じて検出をルーティングしたい場合に設定します。デフォルトでは、Claude Code は最初に RFC 9728 保護リソースメタデータを `/.well-known/oauth-protected-resource` でチェックし、次に RFC 8414 認可サーバーメタデータを `/.well-known/oauth-authorization-server` でフォールバックします。940特定の OAuth 認可サーバーメタデータ URL を指して、デフォルト検出チェーンをバイパスしてください。MCP サーバーの標準エンドポイントがエラーになるとき、または内部プロキシを通じて検出をルーティングしたいときに `authServerMetadataUrl` を設定してください。デフォルトでは、Claude Code は最初に `/.well-known/oauth-protected-resource` で RFC 9728 保護リソースメタデータをチェックし、次に `/.well-known/oauth-authorization-server` で RFC 8414 認可サーバーメタデータにフォールバックします。

713 941 

714`.mcp.json` のサーバー設定の `oauth` オブジェクトに `authServerMetadataUrl` を設定します：942`.mcp.json` のサーバー設定の `oauth` オブジェクトで `authServerMetadataUrl` を設定してください。

715 943 

716```json theme={null}944```json theme={null}

717{945{

733 OAuth スコープを制限する961 OAuth スコープを制限する

734</h3>962</h3>

735 963 

736`oauth.scopes` を設定して、認可フロー中に Claude Code がリクエストするスコープをピン留めします。これは、アップストリーム認可サーバーがより多くのスコープをアドバタイズする場合に、MCP サーバーをセキュリティチームが承認したサブセットに制限するサポートされた方法です。値は RFC 6749 §3.3 の `scope` パラメータ形式と一致する単一のスペース区切り文字列です。964`oauth.scopes` を設定して、認可フロー中に Claude Code がリクエストするスコープをピン留めしてください。これは、アップストリーム認可サーバーがより多くのスコープをアドバタイズするときに、MCP サーバーをセキュリティチームによって承認されたサブセットに制限するサポートされた方法です。値は RFC 6749 §3.3 の `scope` パラメーター形式と一致する単一のスペース区切り文字列です。

737 965 

738```json theme={null}966```json theme={null}

739{967{

749}977}

750```978```

751 979 

752`oauth.scopes` は `authServerMetadataUrl` と `/.well-known` でサーバーが検出するスコープの両方に優先します。MCP サーバーがリクエストするスコープセットを決定するようにするには、設定を解除したままにしてください。980`oauth.scopes` は `authServerMetadataUrl` とサーバーが `/.well-known` で検出するスコープの両方より優先されます。MCP サーバーがリクエストされたスコープセットを決定できるようにするには、設定を解除のままにしてください。

753 981 

754v2.1.196 以降、`oauth.scopes` が設定されていない場合、Claude Code はサーバーの `WWW-Authenticate` ヘッダーまたはその保護リソースメタデータによって提供されるスコープをリクエストし、どちらも提供しない場合は `scope` パラメータを送信しません。自動的に検出された認可サーバーメタデータから完全な `scopes_supported` カタログをリクエストしなくなりました。そのカタログをリクエストすると、管理者のみまたはテンプレートスコープをアドバタイズするアイデンティティプロバイダーが `invalid_scope` エラーで認可リクエストを拒否しました。設定された `authServerMetadataUrl` からフェッチされたメタデータは、その `scopes_supported` をリクエストされたスコープとして提供します。982v2.1.196 以降、`oauth.scopes` が設定されていない場合、Claude Code はサーバーの `WWW-Authenticate` ヘッダーまたは保護されたリソースメタデータによって提供されるスコープをリクエストし、どちらも提供しない場合は `scope` パラメーターを送信しません。自動的に検出された認可サーバーメタデータから完全な `scopes_supported` カタログをリクエストしなくなりました。そのカタログをリクエストすると、管理者のみまたはテンプレートスコープをアドバタイズするアイデンティティプロバイダーが `invalid_scope` エラーで認可リクエストを拒否していました。設定された `authServerMetadataUrl` から取得されたメタデータは、その `scopes_supported` をリクエストされたスコープとして提供します。

755 983 

756認可サーバーが `scopes_supported` で `offline_access` をアドバタイズする場合、Claude Code はそれをピン留めされたスコープに追加して、新しいブラウザサインインなしでアクセストークンを更新できるようにします。984認可サーバーが `scopes_supported` で `offline_access` をアドバタイズする場合、Claude Code はそれをピン留めされたスコープに追加して、新しいブラウザーサインインなしでアクセストークンをリフレッシュできるようにします。

757 985 

758サーバーが後で `insufficient_scope` の 403 を返す場合、Claude Code は同じピン留めされたスコープで再認証します。必要なツールが pin の外側のスコープを必要とする場合は、`oauth.scopes` を拡張してください。986サーバーが後でツール呼び出しに対して 403 `insufficient_scope` を返す場合、Claude Code は同じピン留めされたスコープで再認証します。ピン留めされたセット外のスコープが必要なツールが必要な場合は、`oauth.scopes` を拡張してください。

759 987 

760<h3 id="use-dynamic-headers-for-custom-authentication">988<h3 id="use-dynamic-headers-for-custom-authentication">

761 カスタム認証用の動的ヘッダーを使用する989 カスタム認証に動的ヘッダーを使用する

762</h3>990</h3>

763 991 

764MCP サーバーが OAuth 以外の認証スキーム（Kerberos、短期トークン、内部 SSO など）を使用する場合、`headersHelper` を使用して接続時にリクエストヘッダーを生成します。Claude Code はコマンドを実行し、その出力を接続ヘッダーにマージします。992MCP サーバーが Kerberos、短命トークン、または内部 SSO などの OAuth 以外の認証スキームを使用する場合は、`headersHelper` を使用して接続時にリクエストヘッダーを生成してください。Claude Code はコマンドを実行し、その出力を接続ヘッダーにマージします。

765 993 

766```json theme={null}994```json theme={null}

767{995{

775}1003}