ガイド

Claude Code の MCP 設定：MCP サーバーの追加・共有・トラブルシューティング

公開日：2026年10月30日 · 最終確認：2026年10月30日

MCP（Model Context Protocol）は、AI ツールを接続するためのオープンな標準です。MCP サーバーを使うと、Claude Code がツール、データベース、API に直接アクセスできるので、データをチャットにコピーする必要がなくなります。このページでは、3 種類のトランスポートそれぞれで使うコマンド、設定の保存場所、チームでの共有方法、認証、失敗したときの確認点を手順に沿って説明します。内容は Anthropic の Connect Claude Code to tools via MCP に沿っており、2026 年 10 月 30 日にそのページで確認しました。

MCP とは何か、いつサーバーを接続するか

MCP サーバーを使うと、Claude Code がツール、データベース、API にアクセスできます。課題管理ツールや監視ダッシュボードなど、別のツールからチャットにデータをコピーしていると気づいたら、サーバーを接続する場面です。接続すれば、Claude は貼り付けられた内容に頼らず、そのシステムを直接読んだり操作したりできます。

セキュリティ：各サーバーを接続する前に、信頼できるか確認してください。外部のコンテンツを取得するサーバーは、プロンプトインジェクションの危険にさらされる可能性があります。

トランスポートごとのサーバーの追加方法

どの方法も claude mcp add を使います。サーバーから提供された情報から始めてください。https:// のアドレスならリモートサーバー、npx などの起動コマンドなら自分のマシンで動くサーバーです。

リモート HTTP サーバー

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

JSON 設定では、type フィールドに http の別名として streamable-http を指定できます。url があって type がない JSON のエントリは設定エラーです。Claude Code は type のないエントリを stdio サーバーとして読み取り、スキップします。

リモート SSE サーバー

SSE（Server-Sent Events）トランスポートは非推奨です。利用できる場合は HTTP を使ってください。サービスによっては、いまだに SSE のエンドポイントだけを公開しています。その場合も同じ claude mcp add --transport http <name> <url> コマンドで追加できます。Claude Code はまず HTTP を試し、サーバーが受け付けなければ SSE に切り替えます。この自動切り替えには Claude Code v2.1.265 以降が必要です。それより前のバージョンの場合や、SSE で直接接続したい場合は、--transport sse を渡します。

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

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

ローカルの stdio サーバー

stdio サーバーは、自分のマシン上のローカルプロセスとして動作します。

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• --（ダブルダッシュ）は、--transport、--env、--scope など Claude 自身のオプションと、サーバーを起動するコマンドと引数を区切ります。-- より後ろはそのままサーバーに渡されます。これがないと、Claude Code は --port のようなサーバーのフラグを、自分のオプションとして解析しようとします。
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 は、KEY=value を環境に設定して python server.py --port 8080 を実行します。
• --env は複数の KEY=value のペアを受け付けます。--env の直後にサーバー名を置くと、CLI はその名前を別のペアとして読み取って拒否するので、--env とサーバー名の間に、--transport stdio など別のオプションを最低 1 つ入れてください。

他のクライアント向けの手順を変換する

サーバーのセットアップ手順が Claude Desktop、Cursor、その他の MCP クライアント向けに書かれていて、claude mcp add のコマンドが載っていないことがあります。その中から、URL、起動コマンド、JSON ブロックを探してください。

• URL（https://mcp.example.com/mcp など）：サーバーはリモートです。claude mcp add --transport http example https://mcp.example.com/mcp を使います。
• 起動コマンド（npx -y @example/mcp-server など）：サーバーは自分のマシンで動きます。コマンド全体を -- の後ろに置きます。claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server。
• mcpServers の JSON ブロック：claude mcp add-json には、外側のラッパーではなく、mcpServers の中のオブジェクトを渡します。

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

add-json では、type のない url のエントリには、先に "type": "http"、"type": "sse"、"type": "ws" のいずれかを追加する必要があります。claude mcp add --transport は ws を受け付けないので、WebSocket サーバーは .mcp.json か claude mcp add-json で設定します。サーバー名に使えるのは、英字、数字、ハイフン、アンダースコアだけです。

スコープ：設定の保存場所

MCP サーバーは 3 つのスコープで設定できます。スコープによって、どのプロジェクトでサーバーが読み込まれるか、設定をチームと共有するかどうかが決まります。-s または --scope で選び、デフォルトは local です。

# Local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# Project scope
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# User scope
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

local スコープのサーバーは、~/.claude.json の中で、そのプロジェクトのパスの下に保存されるので、他のプロジェクトには表示されません。個人用の開発サーバー、試験的な設定、バージョン管理に入れたくない認証情報を持つサーバーに使います。なお、MCP サーバーの「local スコープ」は、一般的なローカル設定ファイルである .claude/settings.local.json とは別のものです。

同じサーバーが複数の場所で定義されている場合、Claude Code は、最も優先順位の高いソースの定義を使って 1 回だけ接続します。エントリ全体が使われ、フィールドがスコープをまたいで統合されることはありません。優先順位は、高い順に次のとおりです：local スコープ、project スコープ、user スコープ、プラグインが提供するサーバー、claude.ai のコネクタ。

.mcp.json でサーバーをチームと共有する

project スコープは、設定をプロジェクトのルートにある .mcp.json ファイルに保存します。project スコープのサーバーを追加すると、Claude Code がこのファイルを作成または更新します。バージョン管理にチェックインすれば、チーム全員が同じ MCP ツールを使えます。

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

セキュリティ上の理由から、Claude Code は、対話セッションで .mcp.json ファイルの project スコープのサーバーを使う前に、承認を求めます。その承認の選択をリセットするには、claude mcp reset-project-choices を実行します。

.mcp.json の環境変数

.mcp.json は環境変数の展開に対応しているので、チームで 1 つの設定を共有しつつ、マシン固有のパスや API キーなどの機密値は各自の環境に置けます。サーバーの command、args、env、url、headers の値で、変数を参照できます。

• ${VAR}：環境変数 VAR の値に展開されます。
• ${VAR:-default}：VAR が設定されていればその値に、未設定なら default に展開されます。

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

参照した変数が未設定で、デフォルト値もない場合でも、設定は読み込まれます。Claude Code は claude mcp list に変数が見つからないという警告を出し、展開されていない ${VAR} のテキストをそのまま使います。リモートサーバーの url と headers では、ANTHROPIC_API_KEY や ANTHROPIC_AUTH_TOKEN などの認証情報の変数は、展開されずに空として読み取られます。そうした認証情報をサーバーに渡したいときは、自分で付けた名前の変数にコピーして、その名前を参照してください。

サーバーの一覧表示、確認、削除

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

claude mcp add は成功すると Added ... の行を出力します。これは設定が書き込まれたことを意味します。認証情報は検証されないので、プレースホルダーのトークンも受け付けられ、サーバーは後から接続に失敗します。Claude Code が実際に接続できたか確認するには、claude mcp get <name> を実行するか、Claude Code で /mcp を実行して、サーバーの行にチェックマークが付いているか見てください。

claude mcp list は、各サーバーの横にヘルスステータスを表示します。

リモートサーバーを削除すると、Claude Code は、そのサーバー用に保存した OAuth トークンとクライアント登録も削除しますが、認可サーバー側でトークンを失効させることはしません。認可サーバーが失効に対応している場合は、claude mcp remove <name> の前に、シェルで claude mcp logout <name> を実行してください。

設定を失わずにサーバーを使わないようにするには、/mcp パネルでオフに切り替えます。Claude Code はそのサーバーへの接続をやめ、設定は残します。

リモートサーバーでの認証

クラウドベースの MCP サーバーの多くは認証が必要で、Claude Code は OAuth 2.0 に対応しています。サーバーが 401 Unauthorized または 403 Forbidden を返すと、Claude Code はそのリモートサーバーを認証が必要なものとして扱います。

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

続いて Claude Code 内で /mcp を実行し、ブラウザの手順に従ってログインします。

• 認証トークンは安全に保存され、自動で更新されます。
• アクセスを取り消すには、/mcp メニューの「Clear authentication」を使います。
• ブラウザが自動で開かない場合は、表示された URL をコピーして手動で開きます。
• 認証後にブラウザのリダイレクトが接続エラーで失敗した場合は、ブラウザのアドレスバーにあるコールバック URL の全体を、Claude Code に表示される URL のプロンプトに貼り付けます。
• OAuth 認証は HTTP サーバーで使えます。

セッションを開かずにサインインするには、シェルからフローを実行します。

claude mcp login sentry

保存された認証情報を後で消去するには、claude mcp logout <name> を実行します。SSH セッションや、ディスプレイサーバーのない Linux では、claude mcp login がローカルのブラウザが使えないことを検出し、ブラウザを開く代わりに認可 URL を表示します。その URL を手元のマシンで開き、ブラウザのアドレスバーにあるリダイレクト URL の全体を、プロンプトに貼り付け直してください。この手順には対話的なターミナルが必要なので、ssh -t で接続します。ローカルのブラウザが検出された場合でも URL のプロンプトを強制するには、--no-browser を渡します。

サーバーに headers.Authorization を設定していて、サーバーがそれを拒否した場合、Claude Code は OAuth にフォールバックせず、接続が失敗したと報告します。そのトークンが MCP エンドポイントで有効か確認するか、ヘッダーを削除して OAuth のフローを使ってください。claude -p や Agent SDK の実行には /mcp パネルがないので、先に対話セッションか claude mcp login <name> でサインインしておきます。

タイムアウトと出力の上限

• 起動のタイムアウトは、環境変数 MCP_TIMEOUT で設定します。たとえば MCP_TIMEOUT=10000 claude は 10 秒です。
• 1 つのサーバーのツール呼び出しを制限するには、そのサーバーの .mcp.json のエントリに、ミリ秒単位の timeout フィールドを追加します。たとえば 10 分なら "timeout": 600000 です。これは、そのサーバーに限って、環境変数 MCP_TOOL_TIMEOUT より優先されます。
• Claude Code は、MCP ツールの出力が 10,000 トークンを超えると警告を表示し、デフォルトでは出力を 25,000 トークンに制限します。上限を上げるには、Claude Code を起動する前にシェルで MAX_MCP_OUTPUT_TOKENS を設定します。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

警告のしきい値は固定です。サーバーがツール自身の上限を引き上げない限り、50,000 文字を超える成功したテキスト結果は、この変数にかかわらずファイルに保存されます。

トラブルシューティング

FAQ

参考資料

• Claude Code: Connect Claude Code to tools via MCP（claude mcp add、スコープ、.mcp.json、認証、出力の上限。2026 年 10 月 30 日に確認）