MCP サーバーをつなぐ

MCP（Model Context Protocol）は、外部のツールやデータを Claude Code につなぐオープンな標準です。課題管理、監視、データベースなどのサーバーをつなぐと、貼り付けなしで Claude がその系統を直接読んで操作できます。

最初の1台は、下の「最短の手順」から始めてください。それ以外の設定や細かい挙動はこのページで引けます。

このページで分かること#

• サーバーの種類（HTTP・SSE・stdio・WebSocket）ごとの追加方法
• 保存先を決める3つのスコープ（local・project・user）と、優先順位
• .mcp.json の書き方と、環境変数の展開
• OAuth や headersHelper による認証
• 出力の上限、タイムアウト、ツール検索などの調整
• MCP のプロンプト・リソースの使い方、Claude Code 自身を MCP サーバーにする方法

最短の手順#

ターミナルで（claude の会話の中ではなく）サーバーを登録し、状態を確かめ、会話で使います。

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list
claude

claude mcp add は設定を書き込むだけで、接続や資格情報の確認はしません。つながったかは claude mcp list か、会話の中の /mcp で見ます。用が済んだら claude mcp remove <name> で外せます。接続したサーバーはツール名と指示がコンテキストを少し使うので、使わないものは外しておくと空きが残ります（コンテキスト）。

サーバーを追加する#

リモート HTTP サーバー（推奨）#

クラウドのサービスにつなぐ標準の方法です。

claude mcp add --transport http <name> <url>
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

• JSON の type には、http の別名として streamable-http も書けます
• url があって type が無い項目は、stdio と読まれて設定エラーになり、そのサーバーはスキップされます。"type": "http"（または sse・ws）を足します
• "type": "sdk" のサーバーは、Agent SDK アプリやデスクトップアプリのような SDK ホストだけが登録できます。.mcp.json などに書いてもスキップされます
• --output-format stream-json の実行では、スキップされた --mcp-config の項目が system/init イベントの mcp_server_errors に出ます（v2.1.219 以降）

リモート SSE サーバー#

SSE は非推奨です。使える場合は HTTP を使います。SSE しか出していないサービスも、まず同じ --transport http で追加すると、HTTP を試してだめなら SSE に自動で切り替わります（v2.1.265 以降）。それより前の版や、SSE で直接つなぐときは --transport sse を指定します。

claude mcp add --transport sse asana https://mcp.asana.com/sse
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

ローカル stdio サーバー#

自分のマシンでプロセスとして動くサーバーです。システムへ直接触るツールや自作スクリプト向きです。

claude mcp add [options] <name> -- <command> [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• 起動したサーバーの環境には、プロジェクトのルートが CLAUDE_PROJECT_DIR として入ります。サーバー内で process.env.CLAUDE_PROJECT_DIR（Node）や os.environ["CLAUDE_PROJECT_DIR"]（Python）で読めます
• ルートが固定なのに対し、--add-dir・/add-dir・additionalDirectories で足した作業ディレクトリは、サーバーからの MCP の roots/list 要求への答えに含まれます（起動ディレクトリ＋追加分）。集合が変わると notifications/roots/list_changed が送られます（v2.1.203 より前は起動ディレクトリだけで、通知もありませんでした）
• CLAUDE_PROJECT_DIR はサーバー側の環境の変数なので、.mcp.json や ~/.claude.json の command・args で ${VAR} として参照するなら ${CLAUDE_PROJECT_DIR:-.} のように既定値が要ります。プラグインの MCP 設定では既定値なしで置換されます

リモート WebSocket サーバー#

接続を保ったまま、サーバーが勝手にイベントを送ってくる用途に向きます。要求に応えるだけのサーバーなら HTTP を使います（OAuth と claude mcp add --transport に対応するのは HTTP で、WebSocket はどちらにも対応しません）。.mcp.json か claude mcp add-json で設定します。

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

type: "ws" は、http と同じ url・headers・headersHelper・timeout・alwaysLoad を取ります。認証はヘッダーだけで、固定トークンを headers に置くか headersHelper で生成します。--transport フラグには ws を渡せません。

他のクライアント向けの手順を読み替える#

手順が Claude Desktop や Cursor 向けで claude mcp add が書かれていないときは、中身で見分けます。

mcpServers の JSON を移すときは、ラッパーの外側ではなく、サーバー名の下のオブジェクトだけを渡します。url があって type が無い項目は type を足します。キーが英数字・ハイフン・アンダースコア以外を含むなら、その文字だけで構成したサーバー名を選びます。

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

JSON で追加する#

JSON の設定がすでにあるなら、そのまま渡せます。シェルのエスケープに注意します。--scope user で、プロジェクトでなく自分の設定へ入れられます。

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'
claude mcp get weather-api

Claude Desktop から取り込む#

claude mcp add-from-claude-desktop

対話の画面で取り込むサーバーを選びます。macOS と WSL でだけ動き、標準の場所の設定ファイルを読みます。--scope user で自分の設定へ入れられます。

• 名前が英数字・ハイフン・アンダースコアだけのものは、そのまま引き継がれます。それ以外の文字（空白など）を含む名前は報告されてスキップされ、残りは取り込まれます（v2.1.205 より前は、最初の不正な名前で全体が止まりました）
• 同名のサーバーが既にあると、server_1 のように数字が付きます

追加時のオプションと関連の設定#

claude mcp のサブコマンド#

会話の中では /mcp で状態の確認・認証・再接続・有効無効の切り替えができます。同名のサーバーが複数のスコープにあると remove は exists in multiple scopes と返すので、--scope で消す側を選びます。

スコープ#

スコープで、どのプロジェクトで読み込まれるか、チームと共有するかが決まります。管理者は組織の管理設定からサーバーを配ることもできます。

スコープは追加時に決まります。変えるには、外して別のスコープで入れ直します。Windows では ~/.claude.json は %USERPROFILE%\.claude.json で、CLAUDE_CONFIG_DIR を設定していればその中の .claude.json を読みます。

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

local スコープで追加すると、~/.claude.json の projects の下、そのプロジェクトのパスの mcpServers に入ります。project スコープでは、次のような .mcp.json が作られます。バージョン管理に入れると全員が同じ MCP を使えます。

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

project スコープの承認#

対話セッションでは、.mcp.json のサーバーを使う前に承認を求められます。選択をやり直すには claude mcp reset-project-choices を使います。.mcp.json は起動時に読まれるので、編集したらセッションを開き直します。

claude -p・Agent SDK のセッション・クラウドセッションでは、承認の画面を出せないため、承認なしで読み込みます。bypassPermissions で始めたセッションで、ユーザー設定か管理設定に skipDangerousModePermissionPrompt があるときも同様です。それでも入れたくないときは次のとおりです。

• disabledMcpjsonServers に入れる（どの権限モードでも止まる）
• --setting-sources や SDK の settingSources でプロジェクトの設定を外す
• --strict-mcp-config で始め、--mcp-config で渡したものだけを使う。使わない project サーバーの承認待ちを飛ばすのは v2.1.246 以降です

ワークスペースの信頼と承認#

v2.1.196 以降、claude mcp list と claude mcp get は、そのフォルダを信頼するまで、リポジトリに入っていない設定ファイル由来の承認だけを読みます。クローンしたリポジトリが、自分のサーバーを自分で承認することはできません。リポジトリ内の .claude/settings.json に書いた enableAllProjectMcpServers や enabledMcpjsonServers は、信頼していないフォルダでは無視され、サーバーは ⏸ Pending approval のままです。

信頼していないフォルダでも有効な承認の出どころは、ユーザーの ~/.claude/settings.json、管理設定、--settings で渡した設定です。追跡されていない .claude/settings.local.json の承認は、信頼済みのフォルダでだけ適用されます（ホームや CLAUDE_CONFIG_DIR で指定した設定ディレクトリは例外。v2.1.207 より前は、信頼前でも適用されていました）。どの設定ファイルにあっても、disabledMcpjsonServers の項目は拒否します。

同名のサーバーがあるときの優先順位#

同じサーバーが複数の場所にあると、最も優先度の高い定義で1回だけ接続し、その項目全体を使います（スコープをまたいだフィールドの合成はしません）。

1. local
2. project
3. user
4. プラグインが持つサーバー
5. claude.ai のコネクタ

3つのスコープは名前で、プラグインとコネクタはエンドポイントで重複を判定します。スキームやホストの大文字小文字、スキームの既定ポート（https の :443）、末尾のスラッシュの違いだけなら同じ URL とみなします。パス・クエリ・ユーザー情報・既定でないポートが違えば別のサーバーです。組織が managedMcpServers で配ったサーバーは、これらより上で、重複すると組織の定義が使われます（v2.1.259 以降）。デスクトップアプリの Code タブで、~/.claude.json の最上位と .mcp.json に同名の stdio サーバーがあるときは、~/.claude.json の定義が使われます（デスクトップアプリ）。

.mcp.json の環境変数の展開#

チームで共有する .mcp.json に、マシンごとのパスや API キーを残さず書けます。

展開できるのは、command・args・env・url・headers です。

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

• 未設定で既定値も無い変数は、警告を出しつつ ${VAR} のままの文字列でサーバーを読み込みます。変数を設定するか :-default を付けます
• リモートサーバーの url と headers では、認証情報にあたる変数は、設定済みでも空として読まれます。リポジトリやプラグインが、あなたの Claude Code やクラウドの認証情報を、宛先のサーバーへ送れないようにするためです。:-default も無視されます。Bearer ${ANTHROPIC_AUTH_TOKEN} と書くとサーバーは Bearer だけを受け取り、たいてい 401 で接続失敗になります
• 空として読まれる例：ANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKEN、クラウドの AWS_BEARER_TOKEN_BEDROCK、HTTPS_PROXY・NPM_TOKEN など。API_KEY のようにこの集合の外の名前は、そのまま展開されます。必要なら自分の名前の変数へ値を写して参照します。ANTHROPIC_BASE_URL のようなプロバイダの基本 URL は展開されます（値に資格情報が埋まっている場合を除く）
• 該当する変数を参照したときは、デバッグログ（claude --debug-file /tmp/claude-debug.log）に never expanded toward a remote server を含む行が出ます
• local・project・user のサーバーでは、/mcp の詳細・claude mcp list・claude mcp get に、解決後の値でなく ${VAR} のまま名前で出ます（/mcp の詳細は v2.1.268 以降）。managedMcpServers のサーバーは URL のホストだけが出ます

状態を見る#

claude mcp list は各サーバーの状態を表示します。claude mcp add が Added ... を出すのは設定を書いたことを示すだけで、接続の成否ではありません。was not saved や may not have been saved が出たら、エラー一覧を見ます。

古い Windows コンソールでは ✔・✘ が √・× に見えることがあります。後ろの3つは設定の判断を示すもので、接続は試みません。WebSocket サーバーは claude mcp list に出ないので、claude mcp get <name> か /mcp で見ます。

失敗の詳細は、claude mcp list の状態行（claude mcp get では Issue: 行、/mcp の詳細では Issue: の行）に、HTTP ステータスかエラーコードとサーバーが返したテキストで付きます。資格情報らしい文字列は伏せられ、展開後の URL は出ません（v2.1.219 より前は状態だけでした）。404 のときは MCP endpoint not found at <origin> と出るので、claude mcp get <name> で設定した URL を確かめ、文書にあるパスと比べて入れ直します。

設定の警告#

キャッシュされた状態#

HTTP・SSE サーバーで以前使ったものは、/mcp や /plugin の画面に cached 2h ago · connects on first use · 5 tools のように出ることがあります。前回のセッションで保存したツール一覧を使い、起動時には接続せず、Claude が最初にそのツールを呼ぶときに接続します。ツールは最初のメッセージから使えます。この発見キャッシュは v2.1.221 以降で、既定では切れていて、段階的な展開で有効になっていることがあります。MCP_DISCOVERY_CACHE=1 で有効、0 で無効にします（v2.1.238 より前は既定で有効でした）。/mcp で「Disable」や「Clear authentication」を選ぶと、そのサーバーのキャッシュは破棄されます。「Reconnect」は、接続済みか失敗のサーバーでは破棄し、cached のサーバーでは今すぐ接続してキャッシュを残します。

url が空のリモートサーバーは not configured と表示され、接続は試みません。あとから設定するコネクタの置き場として、プラグインが空の項目を持つことがあります。

ツールの利用可否#

/mcp はサーバーごとのツール数を出し、ツール機能を持つのに1つもツールを出さないサーバーに印を付けます。バックグラウンドで接続中のサーバーのツールが要るとき、Claude はその接続を待ちます。待ち方は構成で変わります。

• ツール検索が有効（既定）：ToolSearch の呼び出しの中で待つ
• ツール検索が無効（ANTHROPIC_BASE_URL を独自にした場合、ENABLE_TOOL_SEARCH=false、Google Cloud の Agent Platform で Claude 4.5 世代より前のモデル）：WaitForMcpServers ツールで待つ
• Azure 上にホストした Microsoft Foundry：ツール検索の経路で始まり、サーバー側の拒否を見て、全ツールを先に読み込む方式へ切り替わる

セッションを再開したあと、保存された会話の中のツールを、その MCP サーバーがまだ接続中のうちに Claude が呼ぶことがあります。サーバーが最初の接続を試みている間、Claude Code は呼び出しを最大 10 秒保留し、ツールが使えるようになったら実行します。時間内に接続できない場合や、失敗してすでに再試行中の場合は、No such tool available のツールエラーで失敗します。

サーバーを外さずに無効にする#

/mcp でサーバーを切ると、設定を残したまま接続しなくなります（一覧には無効として残ります）。選択はプロジェクトごとに ~/.claude.json へ、次の2つのリストのどちらかで保存されます。

各サーバーはどちらか1つのリストだけが見られ、互いを上書きしません。通常のサーバーを enabledMcpServers に入れても、既定で無効な組み込みサーバーを disabledMcpServers に入れても、無視されます。.mcp.json の承認を扱う enabledMcpjsonServers・disabledMcpjsonServers とは別の設定です（設定キー一覧）。

クライアントのランタイム（v1 と v2）#

Claude Code は、起動のたびに2つの MCP クライアントのランタイムのどちらかを選び、終了まで使います。v1 は MCP TypeScript SDK 1.x、v2 は同じコードを SDK 2.0 に載せたもので、プロトコルの 2026-07-28 版が加わります。

• 機能フラグを取得するセッションでは、v2.1.232 以降が v2 を使う
• 機能フラグを取得しないセッションでは、v2.1.274 以降で v2 が既定。対象は、Amazon Bedrock・Claude Platform on AWS・Google Cloud の Agent Platform・Microsoft Foundry のセッション（ホストが CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST を設定した場合を除く）、Claude apps gateway 経由のセッション、DISABLE_TELEMETRY などでテレメトリや機能フラグ取得を切ったセッション

v2 では次も変わります。

• HTTP サーバーに新しい版に対応するかを尋ね、対応するものには新しい版で接続する。claude.ai のコネクタには機能フラグ取得のセッションで尋ねる。機能フラグ取得のセッションでは v2.1.285 以降が、Anthropic の段階的な展開に合わせて stdio サーバーにも尋ねる。コネクタと stdio サーバーにすべてのセッションで尋ねるには MCP_PROTOCOL_NEGOTIATION=auto
• 新しい版のサーバーからの list_changed 通知を、開きっぱなしにしたストリームで受ける
• 新しい版で接続するチャネルサーバーは登録しない（その版はチャネルのメッセージを運べない）
• OAuth のサインインで、認可応答が想定外の発行者を名指ししたら失敗にする
• OAuth の資格情報は、HTTPS か localhost・127.0.0.1・::1 のトークンエンドポイントにだけ送る。それ以外の http:// では失敗する（エラー一覧）

ランタイムを自分で選ぶには MCP_SDK_GENERATION を v1 か v2 に、尋ねるかどうかは MCP_PROTOCOL_NEGOTIATION を auto か legacy にします。Anthropic が機能フラグで、特定のサーバーを前の版のままにすることもあります。

動的なツール更新と再接続#

• サーバーは接続中に、提供するツール・プロンプト・リソースを変えて list_changed 通知を送れます。通知が届いたときの動作は次のとおりです
  • 対話のターミナルセッション：そのサーバーから更新後の一覧を取り直すので、再接続は要らない
  • -p の非対話モードと Agent SDK：これらの通知ではツール一覧だけを更新する
• 更新の取得に失敗したら、次に成功するまで前回の内容を保ちます（v2.1.214 より前は空の一覧に置き換わっていました）
• v2 のストリームが10秒以内にまた閉じると、最大3回まで開き直して止めます。10秒より長く開いたあと閉じる場合は、1時間に5回開き直したあと約6時間待ちます。待っている間は、最後に取得した内容が残ります。早く反映させたいときは /mcp から再接続します

自動の再接続#

リモートサーバーがセッション中に落ちると、指数バックオフで最大5回再接続します（1秒から始めて倍にしていく）。対話セッションでは、その間 /mcp は保留中と表示します。5回失敗すると失敗（サーバーが再認可を求めるなら認証が必要）とし、MCP server "<name>" disconnected · open /mcp to reconnect と通知します。claude -p と Agent SDK も同じ間隔で再接続します。stdio サーバーは自動では再接続されません。

最初の接続が一時的なエラー（5xx・接続拒否・タイムアウト）で失敗した HTTP・SSE サーバーは、最大3回再試行します。再試行しないのは、WebSocket の最初の接続と、認証エラーや not found です（Authorization の唯一の出どころが headersHelper のときは、呼び出しのたびに実行し直すので認証エラーも再試行します）。接続後の tools/list・prompts/list・resources/list は、一時的なネットワーク・サーバーエラーなら短い間隔で最大3回再試行し、認証エラー・4xx・タイムアウトは再試行しません。

失敗したサーバーを自分で再試行する#

失敗した、または認証が要るサーバーをすべて再試行するには、/mcp reconnect all を実行します。対話のターミナルでは v2.1.284 以降が必要で、それより前の版は MCP server "all" not found と出ます。

接続に失敗したサーバーについて、ツール検索が有効なら Claude に失敗したサーバーと理由が伝わり、応答で報告されます（一致するツールが無い ToolSearch の結果にも載ります）。ツール検索が無い構成では伝わりません。

タイムアウトと長いツール呼び出し#

• サーバーごとの timeout は、呼び出しごとの壁時計の上限です。進捗の通知では延びません。HTTP・SSE・claude.ai のコネクタには、最初の応答バイトまでの要求ごとのタイマーもあり、60秒・そのサーバーに適用されるツールのタイムアウト・MCP_TIMEOUT の最大値になります。stdio と WebSocket には要求ごとのタイマーがありません
• 応答も進捗通知も無い状態が続くと、待機の窓を過ぎて中断します。窓は HTTP・SSE・WebSocket・コネクタで5分、stdio で30分が既定です。IDE サーバーと SDK のプロセス内サーバーには適用されません。サーバーごとの timeout（1000以上）は、この窓の下限にもなります（v2.1.203 以降。それより前は stdio は対象外でした）
• メイン会話での MCP ツール呼び出しが2分を超えると、セッションを塞がずバックグラウンドタスクに移ります（v2.1.212 以降）。Claude はタスク ID をすぐ受け取り、結果は完了通知で届きます。/tasks に出て止められますが、セッションを終えると消えます。移らないのは、サブエージェントからの呼び出し、IDE サーバーへの呼び出し、非対話モード（上の変数で許可しない限り）、開いている問い合わせ（elicitation）ダイアログの待ち中の呼び出し（閉じるまで保留）です

プラグインが持つ MCP サーバー#

プラグインは、有効にすると MCP サーバーを一緒に連れてきます。ユーザーが設定したサーバーと同じに動きます。

• 定義は、プラグインルートの .mcp.json か plugin.json の中にインラインで書く
• プラグインを有効にすると自動で起動する。追加・削除はプラグインの導入・削除で行い、/mcp では外せない（無効にする切り替えはできる）
• 有効・無効を会話中に切り替えると、反映のときに接続・切断される。対話端末のないセッションでは /reload-plugins はプラグインの MCP サーバーを接続・切断せず、次のセッションから反映される。設定が変わらないサーバーの接続は、リロードしても保たれる
• v2.1.246 以降は、/cd で作業ディレクトリを移すと、移動先で有効なプラグインのサーバーへ接続し、無効になったものは切断する
• クラウドセッションでは、まだ接続していないプラグインのサーバーへの呼び出しが、そのサーバーを起動して接続を待つ

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": { "DB_URL": "${DB_URL}" }
    }
  }
}

パス用の置換は ${CLAUDE_PLUGIN_ROOT}（インストール先）、${CLAUDE_PLUGIN_DATA}（永続状態）、${CLAUDE_PROJECT_DIR}（プロジェクトルート）です。stdio の command・args・env、http・sse・ws の url・headers・headersHelper で効きます。プラグインの stdio サーバーを claude mcp get すると、Command: stdio・空の Args:・NAME=[REDACTED] が出ます。

プラグインのサーバーのツール名には、プラグイン名とサーバー名が入ります。

mcp__plugin_<plugin-name>_<server-name>__<tool-name>
mcp__plugin_my-plugin_database-tools__query

A-Z・a-z・0-9・_・- 以外の文字は _ に置き換わります。権限ルール、スキルの allowed-tools、サブエージェントの tools、フックのマッチャーでは、この完全な名前を使います。素のサーバー名（mcp__database-tools__.* など）で書いたフックのマッチャーは、プラグインのサーバーには発火しません。サーバー自体は plugin:<plugin-name>:<server-name> の名前で登録され、mcp_tool フックの server のような欄にはこの名前を使います（フックのリファレンス）。作る側の詳細はプラグインを作って配るにあります。

認証#

リモートサーバーの多くは認証が要ります。Claude Code は OAuth 2.0 に対応します。

OAuth でサインインする#

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

会話の中で /mcp を開き、サーバーを選んで「Authenticate」を押すと、ブラウザが開きます。トークンは安全に保存され、自動で更新されます。取り消すには /mcp の「Clear authentication」です。ブラウザが自動で開かないときは表示された URL を手で開きます。認証後にリダイレクトが接続エラーになったら、アドレスバーの完全なコールバック URL を、Claude Code の URL 入力へ貼ります。OAuth が使えるのは HTTP サーバーです。

認証が必要と判断される条件は、サーバーの種類で違います。

• 未サインインのサーバー：401 か 403 で /mcp に認証が必要と出る
• claude.ai のコネクタ：claude.ai がセッショントークンを拒否した場合の 401 は、コネクタの再認可では直らないので、認証が必要とはせず「セッショントークンが拒否された」状態を示す
• headers や headersHelper で Authorization を設定したサーバー：401・403 は認証が必要とはせず、接続失敗として報告する（${VAR} で設定したなら、その変数が空として読まれる集合に入っていないか確かめる）
• クラウドセッションに渡されたコネクタ：サインインは走らせない。claude.ai で認可し直す

すでにサインインした OAuth サーバーが 401 を返すと、保存済みトークンを更新して再接続し、要求を1回だけ再試行します。それでも失敗した場合だけ /mcp で認証が必要と出ます（一時的な理由での更新失敗でセッションの残りが認証必要になる不具合は v2.1.206 で直りました）。サーバーが保存済みのリフレッシュトークンを拒否すると、すぐに /mcp を案内する通知が出ます。/mcp で「Re-authenticate」を選びます。

設定済みサーバーが認証を要するとき、起動時の通知が出ます。数えるのは Claude Code からサインインできるサーバーだけです。各サーバーは1回だけ告知され、再び認証が必要になるまで次回の起動の数から外れます。非対話モードでは /mcp が使えないので、ツール検索が有効なら（v2.1.196 以降）使えないサーバーの名前が Claude に伝わり、対話セッションで /mcp か claude mcp login <name> でサインインします。

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

claude mcp login sentry
claude mcp logout sentry
claude mcp login sentry --no-browser

ローカルのブラウザが使えないとき（SSH・ディスプレイの無い Linux）は、認可 URL が表示されます。自分の手元で開いて、リダイレクト後の完全な URL をプロンプトへ貼ります。貼るには対話端末が要るので ssh -t で接続します。--no-browser で、ブラウザがあっても URL の入力に進めます。

OAuth の戻り先ポートを固定する#

登録済みのリダイレクト URI を要求するサーバー向けです。既定ではランダムな空きポートが使われます。http://localhost:PORT/callback の形の登録に合わせて、--callback-port で固定します。動的クライアント登録（単独）でも、--client-id（事前登録の資格情報）との併用でも使えます。

claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

事前登録した OAuth 資格情報を使う#

「Incompatible auth server: does not support dynamic client registration」と出るサーバーは、動的クライアント登録に対応しておらず、事前に資格情報が要ります（Client ID Metadata Document 方式のサーバーは自動で検出されます）。サーバーの開発者ポータルでアプリを登録してクライアント ID とシークレットを控え、リダイレクト URI を求められたら空きポートで http://localhost:PORT/callback を入力します。

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

add-json の場合は、oauth の中に clientId と callbackPort を書き、シークレットは別に --client-secret で渡します。ポートだけ固定するなら "oauth":{"callbackPort":8080} だけにします。CI では MCP_CLIENT_SECRET=your-secret を前置すると、対話の入力を省けます。登録したら /mcp でブラウザのログインを済ませます。

• シークレットはシステムのキーチェーン（macOS）か資格情報ファイルに保存され、設定には入りません
• シークレットを設定できるのは、サーバーの追加時だけです。claude mcp login や /mcp では保存済みのシークレットが使われ、入力も MCP_CLIENT_SECRET の読み取りもありません。あとから変えるには、claude mcp remove <name> で外して、同じ --scope で --client-secret を付けて入れ直します
• シークレットの無い公開クライアントなら、--client-id だけを使います
• これらのフラグは HTTP と SSE にだけ効き、stdio には効きません。claude mcp get <name> で OAuth 資格情報が設定されているか確認できます
• v2.1.229 だけは http://127.0.0.1:PORT/callback を送っていて、完全一致を求めるサーバーでリダイレクト URI の不一致が出ました。v2.1.231 で localhost に戻っています。v2.1.229 では、更新するか、127.0.0.1 の形も登録に足します

OAuth の設定を上書きする#

.mcp.json のサーバーの oauth に、次のキーを置けます。

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

oauth.scopes は authServerMetadataUrl と /.well-known で見つかるスコープのどちらよりも優先します。未設定のときは、v2.1.196 以降、サーバーの WWW-Authenticate ヘッダーかリソースのメタデータが示すスコープを要求し、どちらにも無ければ scope パラメータを送りません（自動検出したメタデータの scopes_supported の全部は要求しません。invalid_scope で拒否される原因だったためです）。認可サーバーが offline_access を示しているときは、固定したスコープへ自動で足され、ブラウザの再サインインなしにトークンを更新できます。

ツール呼び出しが 403 の insufficient_scope を返すと、needs additional permissions の文でサーバーが求めるスコープが示され、/mcp で認証が必要と出ます。そのスコープが固定した oauth.scopes に無ければ足してから、/mcp で認証し直します。足さずに認証し直しても、トークンにそのスコープは入りません。

headersHelper で動的にヘッダーを作る#

Kerberos・短命なトークン・社内 SSO など OAuth 以外の方式向けです。接続のたびにコマンドを実行し、出力をヘッダーへ合成します。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

コマンドはインラインでも書けます（例：echo '{"Authorization": "Bearer '"$(get-token)"'"}' を JSON 文字列として）。

• コマンドは、文字列のキーと値の JSON オブジェクトを標準出力へ書く
• シェルで実行し、10秒で打ち切る
• 同名の静的な headers は、動的なヘッダーが上書きする
• セッション開始時と再接続のたびに実行し、結果をキャッシュしない（トークンの再利用はスクリプトの側で行う）
• ツール呼び出しが 401・403 を返すと、同じ条件でヘルパーを実行し直し、再接続して1回再試行する。それでも失敗したときだけ認証が必要と出る
• 出力に Authorization ヘッダーがあると、それがサーバーの認証になり、OAuth には戻らない。接続時に拒否されたら、認証が必要でなく接続失敗として報告される。ヘルパーの出力を直してから /mcp で再接続して再実行する
• プラグインが持つ headersHelper は、シェルで解釈されるため ${user_config.*} を参照できず、設定の誤りとして報告される（v2.1.207 以降）。headers へ ${user_config.KEY} を置くか、ヘルパーが設定ファイルから読む

ヘルパーに渡される環境変数は次のとおりです。

ヘルパーの作業ディレクトリ#

相対パスが解決される場所は、サーバーを設定した場所で決まります（Bash での cd では動きません。/cd が動かすのは、セッションの主作業ディレクトリで動くサーバーだけです）。

ヘルパーが読める環境変数#

リポジトリやプラグインが持つ headersHelper は自分で書いていないコマンドなので、認証情報の変数を外して実行します。

• 外される：プロジェクトの .mcp.json・プラグインのサーバー、プロジェクトや --add-dir のエージェントファイルのインラインサーバー
• 外されない：user・local スコープ、管理された MCP、claude.ai のコネクタ、SDK か --mcp-config のもの、~/.claude/agents/・管理設定・--agents のエージェントのインラインサーバー

Git の GIT_CONFIG_KEY_<n> を除き、名前に TOKEN・SECRET・PASSWORD・KEY・AUTH を（大文字小文字を問わず）含む変数と、ANTHROPIC_CUSTOM_HEADERS のような名前の決まりに合わない固定のリストの変数が外されます。必要な資格情報は、ファイルか資格情報ストアから読みます。url にそのような変数の値が入っていると、ヘルパーが受け取る CLAUDE_CODE_MCP_SERVER_URL でも、その部分が REDACTED になります。

ヘルパーの前に信頼が要る#

headersHelper は任意のシェルコマンドです。project の .mcp.json と local スコープのサーバーでは、そのサーバーが宣言されたプロジェクトのディレクトリの信頼ダイアログを承認するまで実行されません（v2.1.238 より前は、claude -p や SDK では確認なしに、対話では親フォルダを信頼していれば実行されました）。親フォルダの信頼や、claude -p・SDK が設定ファイルのフックに対して自動で得る信頼は数えません。信頼するまでは静的な headers だけで接続し、claude -p や SDK では headersHelper not run の行がサーバーごとに標準エラーへ出ます。ダイアログなしで信頼するには、~/.claude.json の projects["<パス>"].hasTrustDialogAccepted を true にします。同じ規則は、エージェントファイルにインラインで書いたサーバーにも当てはまり、そのプロジェクトやディレクトリを信頼するまではサーバー自体が読み込まれません。

claude.ai のコネクタを使う#

claude.ai のアカウントでログインしていれば、claude.ai で追加した MCP サーバー（コネクタ）が Claude Code でも自動で使えます。追加は claude.ai の画面（Team・Enterprise では管理者だけ）で行い、Claude Code では /mcp に、claude.ai 由来の印付きで出ます。Anthropic が用意するコネクタもあります（Claude Docs が使えるアカウントでは、/mcp に claude.ai Claude Docs が設定なしで出ます）。

• 組織が claude.ai で認証を管理しているコネクタは managed と出ます
• 一度もサインインしていないコネクタは、claude.ai の節の最後の Show unused connectors の行にたたまれます
• コネクタが取得されるのは、有効な認証方式が claude.ai のサブスクリプションのログインのときだけです。ANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKEN・apiKeyHelper、Bedrock や Google Cloud の Agent Platform のようなサードパーティのプロバイダ、ANTHROPIC_PROFILE やフェデレーション、claude setup-token の CLAUDE_CODE_OAUTH_TOKEN が有効なときは読み込まれません。出てこないときは /status で認証方式を確かめ、その設定を外して /login で claude.ai のアカウントを選びます
• 起動時に一時的なネットワークの問題で一覧が取れないときは、バックグラウンドで最大3回再取得します。それでも出なければ再起動します
• /mcp が session token rejected を示したら、claude.ai が Claude Code のログインのトークンを拒否しています。コネクタの再認可では直らないので、/login でサインインし直して /mcp から再接続します（v2.1.222 より前は、認証が必要と表示されていました）
• Claude Code で追加した同じ URL のサーバーが優先され、コネクタは hidden と表示されます
• Microsoft 365・Gmail・Google Calendar など、Anthropic がホストするコネクタの一部は、上流の認証基盤が claude.ai の登録したリダイレクト URL しか受けないため、ローカルの OAuth に対応しません。claude mcp add や .mcp.json でそのホストを追加すると is Anthropic-hosted and doesn't support local OAuth と出ます。自分の項目を claude mcp remove し、claude.ai でつなげば、Claude Code に自動で現れます

コネクタが届く経路#

どの設定が効くかは、セッションの動く場所で変わります。

disableClaudeAiConnectors、ENABLE_CLAUDEAI_MCP_SERVERS、allowAllClaudeAiMcps は、1行目（Claude Code が自分で取得するもの）にだけ効きます。クラウドでは、セッションに届く allowedMcpServers・deniedMcpServers の項目が、渡されたコネクタにも効きます。プロキシがコネクタの URL を書き換えるので、コネクタ自身の URL で書いた serverUrl のパターンは一致しません。ホストに managed-mcp.json があるときは、allowAllClaudeAiMcps の有無にかかわらず、渡されたコネクタは落とされます。デスクトップアプリのローカル・SSH セッションでは、コネクタは type: "sdk" のプロセス内サーバーとして登録され、MCP の設定も managed-mcp.json も届きません。自分のセッションから外すには、claude.ai のコネクタ画面で接続を外します。

組織によるコネクタのツール制御#

組織は、claude.ai のコネクタにツールごとの制御を置けます。Claude Code は起動時にこれを読んで手元で強制します（デスクトップアプリのローカル・SSH セッションを除く。そこではアプリが blocked のツールを渡す前に外し、ask は届かないので通常の権限ルールが適用されます）。

• ask：呼び出しのたびに、Your organization requires approval for this tool の理由で確認する。acceptEdits・auto・bypassPermissions でも出て、記憶する選択肢はなく、一致する許可ルールでも飛ばせない。確認を出さない dontAsk では呼び出しを拒否する
• blocked：Claude に見える前にツールを外す。Claude Code が自分で取得するセッションでは、/mcp のツール一覧に disabled by your organization の印で残る

claude.ai のコネクタを無効にする#

disableClaudeAiConnectors を true にします。どの設定スコープでも効き、どこかで true なら有効になります（プロジェクトの false で、ユーザーや組織の true を打ち消せません）。--mcp-config で明示的に渡したサーバーには影響しません。

{
  "disableClaudeAiConnectors": true
}

環境変数 ENABLE_CLAUDEAI_MCP_SERVERS=false を付けて起動しても、そのシェルのセッションだけ同じ効果です。個別に止めるには、deniedMcpServers へ名前か URL パターンで入れます（serverName に "claude.ai Slack" など）。/mcp で、そのプロジェクトだけコネクタを切り替えることもできます。

Claude Code を MCP サーバーとして使う#

claude mcp serve

起動しても何も出力しません。stdio の MCP サーバーは標準入出力で話すので、端末が無反応なのは、クライアントの接続を待っている正常な状態です。Claude Desktop の claude_desktop_config.json に次を足すと使えます。

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

この MCP サーバーが出すのは Claude Code のツールだけです。個々のツール呼び出しのユーザー確認は、接続する側のクライアントが実装します。

出力の上限と警告#

大きな出力でコンテキストが埋まるのを防ぎます。

「文字数の上限」と「エラーの結果」の2つは、フォアグラウンドで終わった呼び出しに当たります。バックグラウンドのタスクへ移った呼び出しは、結果をタスクの通知で返します。

画像を含まない成功した結果がトークンの上限を超えると、ファイルに保存し、会話にはそのパスを示すメッセージが入ります。Claude は必要なときにそのファイルを読みます。保存先は、そのセッションの tool-results ディレクトリ（~/.claude/projects/ の下。.claude ディレクトリ）です。

サーバーの作者は、tools/list の項目の _meta["anthropic/maxResultSizeChars"] で、そのツールの閾値を引き上げられます。既定のしきい値は 50,000 文字です。上限は50万文字で、データベースのスキーマのような大きいが必要な出力に向きます。

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

ツール結果の画像#

MCP ツールが PNG・JPEG・GIF・WebP を返すと、Claude は会話の中でその画像を見ます。会話内の画像はモデルの大きさの上限に合わせて縮小・圧縮されることがあります。原本のバイトは、セッションの tool-results ディレクトリ（~/.claude/projects/ の下）に保存され、パスが Claude に渡るので、Bash などで切り抜き・変換できます。--no-session-persistence か CLAUDE_CODE_SKIP_PROMPT_HISTORY でセッションの保存を切ると、ファイルは書かれません。画像の保存は v2.1.283 以降です。

ツールの入力スキーマ#

ルートに anyOf・oneOf・allOf があるもの#

Claude API は、スキーマのルートの anyOf・oneOf・allOf を受け付けません（properties の中に入れ子にしたものは、そのまま送ります）。ルートにあるツールは使えなくなるわけではなく、1つのオブジェクトに平たくしてから送り、ツールの説明の先頭に、どの引数のまとまりが組になるかの1文を足します。

• allOf：すべての枝のプロパティを合成し、各枝の required は有効なまま
• anyOf・oneOf：すべての枝のプロパティを合成し、各枝の required はスキーマで強制せず、ツールの説明に書く

サーバーは Claude が選んだ引数をそのまま受け取るので、組み合わせの検証はサーバー側で続けます。API が受け付けるスキーマを作れない場合や、書き換えを有効にするリモート設定が届かない環境では、そのツール1つだけを読み飛ばし、理由をサーバーのログに残して、ほかのツールは使えるままにします。

不正な入力スキーマ#

API は、リクエスト内のどれか1つのツールのスキーマが不正でも、リクエスト全体を400で拒否します。そのため Claude Code は、サーバーのツールを読み込むときに API のチェックのうち2つを自分で走らせ、通らないツールだけを除外します。

• 最上位のプロパティ名は1〜64文字で、ASCII の英数字・_・.・- だけ
• スキーマは JSON Schema draft 2020-12 のメタスキーマに適合する（$schema が無いもの、draft 2020-12 を宣言するものに適用。ほかの方言を宣言するものは、この検査を飛ばす）

除外したときは、理由がサーバーのログに残り、どのツールをなぜ除外したかが Claude に伝わります（Claude に聞けば分かります）。サーバー側でスキーマを直せば、次の読み込みで戻ります。この除外は、Anthropic から取得する機能フラグで有効になります。機能フラグの取得が切れた環境や、フラグが一度も届いていない環境（エアギャップなど）では、検査は走って、拒否されるツールをサーバーのログに残すだけで、スキーマは API へそのまま送られ、400 になります（エラー一覧）。v2.1.216 より前は、どこでも検査がありませんでした。

特定のツールに承認を必須にする#

サーバーの作者は、tools/list の項目の _meta["anthropic/requiresUserInteraction"] を JSON の真偽値 true にして、呼び出しごとの明示的な承認を必須にできます（true 以外は無視されます）。

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

• 呼び出しのたびに確認が出る。acceptEdits・auto・bypassPermissions でも出て、「今後は聞かない」の選択肢はなく、一致する許可ルールでも飛ばせない。確認を出さない dontAsk では呼び出しを拒否する
• 確認は人に届く必要がある。--permission-prompt-tool を使う非対話モードでは、印の付いたツールに対する allow は MCP tool requires user interaction; not supported via --permission-prompt-tool で拒否に変わる。Agent SDK の canUseTool は呼び出しを受け取り、承認できる
• リモートコントロールや SDK アプリの1タップ承認は出さず、完全な確認を出す。端末のダイアログでしか全体を出せない権限要求（安全の警告や、常に許可の選択肢を持つもの）も同様で、リモートコントロールからは答えられず、端末で答える（v2.1.214 以降。リモートコントロール）

同意やアクセス許可のように、確認そのものが目的のツールに向きます。同じサーバーの他のツールは通常どおりです。

問い合わせ（elicitation）に答える#

MCP サーバーは、作業の途中で、自分で得られない情報の入力を求めることがあります。設定は要らず、求められると対話ダイアログが自動で出て、答えがサーバーへ戻ります。

• フォーム形式：サーバーが定義した入力欄のダイアログが出る。記入して送信する
• URL 形式：リンクをブラウザで開いてよいか尋ねる。サインインのように、端末の外で終わる流れに使われる

URL 形式では、URL がコマンドライン引数として OS の URL ハンドラへ渡され、長さに上限があります。コマンドライン用にエスケープしたあとの URL が上限を超えると、拒否しかできません。% や & のようにエスケープが要る文字は、1文字で4文字分（自分と3つのエスケープ）に数えられます。該当文字が無い URL なら約8,000文字、3文字に1つが % のような URL なら約4,000文字が目安です。

ダイアログを出さずに自動で応答するには、Elicitation フックを使います（フックのリファレンス）。プロトコルの 2026-07-28 版で接続すると、クライアントの機能として elicitation: {form: {}, url: {}} を宣言するので、サーバーは標準の要求でどちらの形式も求められます。

MCP リソースを使う#

サーバーが公開するリソースを、ファイルと同じく @ で参照できます。

• @ を入力すると、接続中のすべてのサーバーのリソースが、ファイルと並んで候補に出る（あいまい検索できる）
• 書式は @server:protocol://resource/path
• 1つのプロンプトで複数のリソースを参照できる
• 参照したリソースは、自動で取得されて添付になる

Can you analyze @github:issue://123 and suggest a fix?
Compare @postgres:schema://users with @docs:file://database/user-model

サーバーが対応していれば、リソースの一覧と読み取りのツールも自動で用意されます。ui:// の URI か text/html;profile=mcp-app のメディアタイプを持つ MCP Apps の UI リソースは、ホストが描画するためのもので、@ の候補にも一覧ツールの結果にも出ません（UI リソースだけを持つサーバーは、リソース一覧が空に見えます。URI を指定して読むことはできます）。

ツール検索でツール数に備える#

ツール検索は、MCP ツールの定義を、Claude が必要になるまで読み込まずにおく仕組みです。起動時に読まれるのはツール名とサーバーの指示だけなので、サーバーを増やしてもコンテキストへの影響は小さく、サーバーごとのツール数の上限もありません（実質の上限はコンテキストの予算）。Azure 上にホストされた Microsoft Foundry の配備は、サーバー側が拒否するため、ツール検索を使わず MCP ツールを先に読み込みます（ENABLE_TOOL_SEARCH では上書きできません）。

サーバーの作者へ：ツール検索では、サーバーの指示欄が、Claude がいつツールを検索すべきかの手がかりになります（スキルと似ています）。扱う作業の種類、検索してほしい場面、主な機能を、簡潔に書きます。各ツールの説明とサーバーの指示は、既定で2,048文字で切られるので、大事な点は先頭に置きます。全サーバーの上限は CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH（文字数。v2.1.280 以降）で変えられます。

ツール検索の設定#

既定では有効で、MCP ツールは後回しにされ、必要なときに見つけます。ANTHROPIC_BASE_URL が自社以外のホストを指すときは無効になります（多くのプロキシは tool_reference ブロックを通さないため。ENABLE_TOOL_SEARCH を明示すれば上書きできます）。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定すると無効のままになり、ENABLE_TOOL_SEARCH でも上書きできません（組織は管理設定で、v2.1.227 以降は有効に保てます）。tool_reference ブロックに対応するモデル（Claude Sonnet 4.5・Haiku 4.5・Opus 4.5 以降）が必要です。Google Cloud の Agent Platform では、Opus 4.5・Sonnet 4.5・Haiku 4.5 以降は既定で有効、それより前のモデルは全ツールを先に読み込み、ENABLE_TOOL_SEARCH=true でも上書きできません（v2.1.221 より前は、true を設定しない限りすべてのモデルで無効でした）。

ENABLE_TOOL_SEARCH=auto:5 claude
ENABLE_TOOL_SEARCH=false claude

settings.json の env に書いても設定できます（設定キー一覧）。ToolSearch ツールだけを無効にするには、権限の deny に入れます。

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

サーバーを後回しの対象から外す#

毎ターン使うツールは、サーバーの設定で alwaysLoad を true にすると、ENABLE_TOOL_SEARCH にかかわらず、起動時にそのサーバーのすべてのツールが読み込まれます。先に読むツールはそのぶんコンテキストを使うので、少数のツールに絞ります。alwaysLoad はすべてのサーバーの種類で使えます。

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

サーバーはツールの _meta に "anthropic/alwaysLoad": true を入れて、個別のツールだけを常時読み込みにもできます。alwaysLoad: true のサーバーでは、最初のプロンプトを作るときにツールが必要なため、起動がそのサーバーのツールを待ちます（標準の5秒の接続タイムアウトが上限）。有効な cached を持つリモートサーバーは、接続せずキャッシュからツールを出すので、起動を待たせません。ほかのサーバーは既定ではバックグラウンドで接続し、起動時にも待たせるには MCP_CONNECTION_NONBLOCKING=0 を設定します。

MCP のプロンプトをコマンドとして使う#

サーバーが公開するプロンプトは、Claude Code のコマンドになります。/ で一覧を開くと、/servername:promptname (MCP) として出ます。/mcp__servername__promptname と打っても実行できます。引数はスペース区切りで、空白で分割されるので1語が1つの引数です。

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue login-bug high

• プロンプトは、接続中のサーバーから動的に見つかる。引数は、プロンプトが定義したパラメータに従って解釈され、結果は会話へそのまま入る
• /mcp__servername__promptname の形では、サーバー名のうち A-Z・a-z・0-9・_・- 以外の文字が _ に置き換わる。プロンプト名はサーバーの宣言のまま
• anthropic-skills という名前のサーバーのプロンプトは出ません。claude.ai から同期するスキルのために予約された名前なので、MCP の設定でサーバーの名前を変えます（ツールは使えます）

使い方の例#

GitHub でコードレビュー#

GitHub のリモートサーバーは、パーソナルアクセストークンをヘッダーで渡します。GitHub のトークン設定で、使うリポジトリへのアクセスを持つ fine-grained のトークンを作ります。

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

claude mcp add は資格情報を検証しないので、仮の値でも登録できますが、あとで接続に失敗します。/mcp で connected と出るか確かめます。認証情報が違うと failed になり、詳細に 401 のようなステータスが出ます。そのうえで「Review PR #456 and suggest improvements」「Show me all open PRs assigned to me」のように頼めます。

PostgreSQL に問い合わせる#

@bytebase/dbhub は、--dsn の接続文字列で関係データベースへつなぐ MCP サーバーです。Claude の実行するクエリがデータを変えないよう、接続文字列には読み取り専用のユーザーを使います。

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

/mcp で db が connected になれば、「Show me the schema for the orders table」のように自然な文で聞けます。

サーバーを探す・作る#

審査済みのコネクタは Anthropic Directory で探せ、そこにあるリモートサーバーは claude mcp add で追加できます。自作するなら、MCP の公式ガイドと、Claude のコネクタの開発ドキュメント（認証・テスト・Directory への申請）を見ます。公式の mcp-server-dev プラグインに雛形を作らせることもできます。VS Code 拡張やデスクトップアプリでは、次のコマンドの代わりに プラグインを使う のインストール手順に従います。ターミナルでは claude で Claude Code を起動し、プロンプトに次を入力します。

/plugin install mcp-server-dev@claude-plugins-official
/mcp-server-dev:build-mcp-server

インストールが Marketplace "claude-plugins-official" not found で失敗したら、/plugin marketplace add anthropics/claude-plugins-official を実行してからやり直します。サマリに Run /reload-plugins to activate. と出たら、Claude Code が続けてそのリロードを行います。次のメッセージが会話を読み直すことになる、という警告が出たときは /reload-plugins --force を実行します。実行すると Claude が用途を尋ね、リモート HTTP かローカル stdio のサーバーの雛形を作ります。

チャネル#

MCP サーバーは、CI の結果・監視アラート・チャットのような外部のイベントを、セッションへ直接押し込めます。サーバーが claude/channel の機能を宣言し、起動時に --channels で有効にします（チャネル）。v2 のランタイムで、チャネルサーバーが 2026-07-28 版で接続すると、チャネルのメッセージを運べないため、チャネルとして登録されません。その版に対応しないチャネルサーバーは前の握手で接続し、従来どおり登録されます。

stdio サーバーにその版を尋ねるのは、MCP_PROTOCOL_NEGOTIATION を auto にしたときです。Anthropic は、v2.1.285 以降で Claude Code が機能フラグを取得するセッションでは、これを既定でオンにする展開も進めています。stdio のチャネルサーバーを前の握手のままにするには、MCP_PROTOCOL_NEGOTIATION を legacy にします（全サーバーが前の握手のままになります）。

トラブル対処#

HTTP サーバーは、まず URL に届くかを確かめます（PowerShell では Invoke-WebRequest の別名と区別するため curl.exe）。

curl -I https://mcp.sentry.dev/mcp

• 404 か 405：サーバーは動いている（MCP のエンドポイントは POST にしか応えないものが多く、手元から届く確認にはなる）
• 401 か 403：サーバーは動いていて、認証が要る。ブラウザでのサインインか、GitHub のようにトークンなら --header "Authorization: Bearer <token>" で渡す
• 応答なし：URL とネットワークを確かめる

stdio サーバーは、設定したコマンドを端末でそのまま実行し、本当のエラーを見ます。起動して入力を待つならサーバー自体は動いているので、claude mcp get <name> に出るコマンドが、打ったものと同じかを比べます。違えば -- を省いた可能性が高く、外して -- を付けて入れ直します。.mcp.json を手書きしたなら、構文と置き場所を確かめます（v2.1.285 より前は、type の無い stdio の項目に claude mcp get が Command 行を出さず、そのときは claude mcp list で見られます）。エラーが出るなら、メッセージが Node.js やブラウザなど、足りないものを示します。

その他のエラーの文言はエラー一覧、全体の切り分けはトラブルシューティングを見ます。

組織での管理#

組織が使えるサーバーを一元的に管理する方法（固定の managed-mcp.json、全員へ配る managedMcpServers、allowedMcpServers と deniedMcpServers による制限、ブロックされたときの見え方）は、組織への導入と管理設定から辿れます。

他の画面から#

CLI 以外にも、デスクトップアプリ（コネクタの画面。デスクトップアプリ）、VS Code（VS Code と JetBrains）、クラウドセッション（リポジトリに .mcp.json をコミットすると、リポジトリ1つのセッションで読み込まれる。クラウド（Web））から MCP サーバーをつなげます。claude.ai の claude.ai/customize/connectors で追加したコネクタは、同じアカウントでログインした CLI に自動で読み込まれます。