MCP サーバーを繋ぐ

段	達成したと言える状態
1. 触る	ターミナル`claude mcp add --transport http <name> <url>` でサーバーを 1 つ足し、`claude mcp list` が `✔ Connected` を返したデスクトップ+ ボタン → Connectors を開き、接続済みのものを一覧した
2. 入れる	ターミナル常用するサーバーをスコープ（local / project / user）を選んで登録し、使わないものは `/mcp` で無効にしてあるデスクトップConnectors が MCP サーバーの GUI 設定であることを踏まえ、一覧に無いものは設定ファイルで足している
3. 効かせる	ターミナルtool search とタイムアウトの効き方を踏まえ、接続失敗や呼び出しが返らないときに `claude mcp get <name>` の詳細から切り分けられるデスクトップ`claude_desktop_config.json` の定義が同名の `.mcp.json` / `~/.claude.json` より優先されるという Desktop 固有の順序を言える

何のためのものか

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

接続前に各サーバーを信頼できるか確認する。 外部コンテンツを取得するサーバーは prompt injection のリスクをもたらしうる。

種類	コマンド
Remote HTTP（推奨）	`claude mcp add --transport http <name> <url>`
Local stdio	`claude mcp add [options] <name> -- <command> [args...]`

追加する。stdio では -- の後がそのままサーバーの起動コマンドになる
claude mcp list で健全性を見る（✔ Connected / ! Needs authentication / ✘ Failed to connect）
セッション内では /mcp で状態を確認する

認証が要るサーバーは claude mcp login <name> でシェルから OAuth フローを実行できる。

スコープを選ぶ。ここを間違えると「自分だけのはずが共有された」「共有したいのに他の人に見えない」が起きる。

.mcp.json では ${VAR} と ${VAR:-default} の環境変数展開が使える（command / args / env / url / headers）。未設定で既定値も無いと、${VAR} のテキストがそのまま使われる
使わないサーバーは /mcp パネルでトグルオフする。設定は残ったまま、プロジェクトごとの選択として ~/.claude.json に記録される
project スコープのサーバーは対話セッションで承認を求められる。 選択のやり直しは claude mcp reset-project-choices

tool search が既定で有効。 MCP ツールは upfront に読み込まれず、セッション開始時にはツール名とサーバーの instructions だけが入る。サーバーごとの固定のツール上限は無く、実質の上限はコンテキストウィンドウの予算
常に読み込ませたいサーバーだけ alwaysLoad: true を付ける（起動時にそのサーバーのツールを待つ）
タイムアウトは 3 種類ある。 起動時の MCP_TIMEOUT、ツール呼び出しごとの実時間上限（.mcp.json の timeout / MCP_TOOL_TIMEOUT）、応答も進捗も無いときに打ち切る idle timeout（CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT。既定は HTTP 系 5 分、stdio 30 分）
2 分を超えた呼び出しは自動でバックグラウンドへ移る。 /tasks に現れ、そこで停止できる
出力にも上限がある。 10,000 トークンで警告、既定の上限 25,000 トークン（MAX_MCP_OUTPUT_TOKENS）。超えるとディスクに退避されファイル参照に置き換わる
切れたときは claude mcp get <name> の Issue: 行を読む。HTTP / SSE は指数バックオフで最大 5 回自動再接続するが、stdio はローカルプロセスなので自動再接続しない

url があるのに type が無い JSON エントリは読み込まれない。 stdio として解釈され、スキップされて警告が出る
claude -p・Agent SDK・cloud セッションは project スコープのサーバーを確認なしに読み込む。 承認プロンプトを出せないため。外すには disabledMcpjsonServers
クローンしたリポジトリは自身のサーバーを承認できない。 workspace trust の承認まで ⏸ Pending approval のまま
plugin 由来のサーバーはツール名が違う。 mcp__plugin_<plugin-name>_<server-name>__<tool-name> の形になるので、素のサーバーキーで書いた hook matcher は発火しない
繋いだサーバーの数だけ起動時の読み込みが増える。 tool search が効いていてもツール名とサーバーの instructions は入るので、使わないものはトグルオフする
SSE トランスポートは非推奨。可能なら HTTP を使う