目次

MCPを使うと、Claude Codeから別のプログラムやホスト型サービスが提供するツールを利用できます。課題やデータベースの検索結果をチャットに貼り付ける代わりに、それらを扱うサーバーへのアクセスを与える仕組みです。読み取りや変更ができる範囲は、サーバーの機能と付与した権限によって決まります。

最初は、Claude Codeの公式クイックスタートにあるドキュメントサーバーを使うと始めやすいでしょう。別のアカウントやトークンが不要なので、認証を加える前に設定の流れを学べます。私たちはこれらの例を実際には実行していません。

1. サーバーを1つ追加して接続を確認する

先にClaude Codeをインストールし、Claude Code自体へのログインを済ませます。サーバーを使いたいプロジェクトでターミナルを開いてください。空のディレクトリでも構いません。既存のclaude会話内ではなく、ターミナルで次を実行します。

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

claude-code-docsは自分で選ぶ識別名です。ツールの表示や、設定の確認・削除に使います。--transport httpは、ローカルプログラムを起動するのではなく、ホストされたURLへ接続する指定です。

Added ...とFile modified:が表示されれば、設定が保存されたことを示します。接続や認証情報が有効だと確認できたわけではありません。別途、次を実行します。

bash
claude mcp list
claude mcp get claude-code-docs

ドキュメントサーバーで期待する状態は✔ Connectedです。続いてclaudeを起動し、Use the claude-code-docs server to look up what MCP_TIMEOUT doesと依頼します。サーバー名を指定すると、使いたいツールが明確になります。ツールの権限確認が出たら内容を読み、適切であれば承認します。回答がもっともらしいだけでMCPが使われたと判断せず、ツール呼び出しの横にサーバー名があるか確かめてください。

試した設定を消すならclaude mcp remove claude-code-docsを使います。使わないサーバーもツール名や説明でコンテキストを使うため、必要なものだけ残すと余分な負担を減らせます。

2. サーバーに合うトランスポートを選ぶ

サーバー提供元の設定手順から始めましょう。URLと起動コマンドは別の入力です。

トランスポート向いている用途設定方法
HTTP一般的なホスト型MCPサービスclaude mcp add --transport http <name> <url>
SSESSEエンドポイントを提供し続けているサービス対応版のHTTPフォールバック、または--transport sse
stdio自分のコンピューターで動くプログラム起動コマンドを--の後に置く
WebSocketリモート側からイベントをプッシュするサービスJSONで"type": "ws"を指定

リモート接続にはHTTPが推奨されています。JSONでは"type": "http"に加え、別名の"streamable-http"も使えます。urlだけでtypeがない設定は不十分です。typeを省くとstdioと解釈され、URLだけの不正なエントリーは読み飛ばされます。

SSEは非推奨ですが、利用不可になったわけではありません。Claude Code v2.1.265以降では、--transport httpが最初にHTTPを試し、サーバーが受け付けなければSSEへ切り替えます。以前の版や、直接SSEで接続したい場合は--transport sseを使います。提供元にHTTPがあれば、そちらを優先してください。

ローカルの例として、クイックスタートではNode.js 18以降が必要なPlaywrightを使っています。

bash
claude mcp add playwright -- npx -y @playwright/mcp@latest

--以降はすべてサーバーの起動コマンドです。この区切りを省くと、サーバー用のフラグをClaude Code自身のものとして解釈する場合があります。初回はnpxのダウンロード中に接続確認が失敗することがあるので、完了後に確認し直します。自分のコンピューターでコードを動かすため、信頼できるパッケージを選んでください。

WebSocketはOAuthに対応せず、claude mcp add --transportもwsを受け付けません。.mcp.jsonまたはclaude mcp add-jsonで"type": "ws"を設定します。認証はヘッダーを使い、動的な生成には対応するheadersHelperを利用できます。リモートという理由だけでWebSocketを選ぶ必要はありません。リクエストに応答するツールにはHTTPのほうが適しています。

3. 設定を使う範囲を決める

トランスポートは動かし方、スコープは設定が利用可能になる場所を決めます。localスコープのHTTPサーバーも接続先はリモートです。ここでのlocalはstdioという意味ではありません。

スコープ利用範囲保存場所
local、既定値自分だけ、現在のプロジェクトだけ~/.claude.json内のプロジェクト別エントリー
project現在のリポジトリを使う人プロジェクト直下の.mcp.json
user自分だけ、すべてのプロジェクト~/.claude.jsonの最上位mcpServers

試す段階ならlocal、チームで共有するならproject、どのプロジェクトでも使う個人用ツールならuserを選びます。MCPのlocalスコープは.claude/settings.local.jsonではありません。Windowsの~/.claude.jsonは%USERPROFILE%\.claude.jsonです。CLAUDE_CONFIG_DIRを指定した場合は、その設定ディレクトリ内へ移ります。

最初の例をuserスコープへ移すには、localの定義を削除してから追加し直します。

bash
claude mcp remove claude-code-docs --scope local
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

チーム共有なら--scope userの代わりに--scope projectを使います。同名の定義ではlocal、project、userの順に優先され、採用された設定全体が使われます。項目ごとのマージではありません。それ以外の通常の提供元はこの3つより下ですが、組織のmanagedMcpServersはv2.1.259以降で上位になります。URLを直しても変わらないときは、実際に採用されている定義を確認してください。

4. JSONは正しいファイルに置く

プロジェクト直下の最小限の.mcp.jsonには、同じドキュメントサーバーを次のように書けます。

json
{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

最上位キーはserversではなくmcpServersです。ファイルを.claude/の下へ置かないでください。settings.jsonにmcpServersを書いても読み込まれません。.mcp.jsonは起動時に読み込むため、変更後はセッションを再起動します。

対話セッションではprojectスコープのサーバーに承認を求めます。リポジトリの設定を承認する前にURLやコマンドを確認しましょう。承認画面を閉じた場合は/mcpを開きます。以前の選択をリセットするにはclaude mcp reset-project-choicesを使います。非対話のclaude -pは確認を表示できず、projectサーバーを質問せずに読み込むため、自動化の前に共有設定を確認してください。

別クライアントのJSONをclaude mcp add-jsonに渡す場合は、外側のmcpServersキーを含めず、その中にある1つのサーバー定義だけを渡します。サーバー名に使えるのは英数字、ハイフン、アンダースコアです。

5. OAuthとトークンヘッダーを区別する

OAuthを使うホスト型サービスでは、提供元が案内するMCP URLを追加してから状態を見ます。! Needs authenticationは故障ではなく、次の認証が必要という意味の場合があります。セッション内で/mcpを開き、サーバーを選び、Authenticateを実行します。対話可能なターミナルでclaude mcp login <name>を実行しても構いません。<name>を設定した名前に置き換えます。

ブラウザーが開かなければ、Claude Codeが表示する認可URLを使います。ブラウザーのコールバックが失敗したら、完全なコールバックURLをClaude Code自身の入力欄へ貼り付けます。そのURLをチケットやチャットで共有しないでください。OAuth用の/mcp画面がないclaude -pを始める前に、ログインを済ませます。

固定トークンを使うサービスでは、代わりに認証ヘッダーを渡します。次の例では、アドレス・名前・トークンはプレースホルダーです。例の認証情報をそのまま使わず、提供元の値に置き換えてください。

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

実際のトークンを共有設定へコミットしないでください。JSONでは"Authorization": "Bearer ${API_KEY}"のような環境変数参照が使えます。API_KEYはそのサーバー専用に自分で用意する変数です。貼り付けたトークンの前後に余分な空白や改行がないかも確認します。

設定したAuthorizationヘッダーが401または403で拒否された場合、Claude CodeはOAuthへ切り替えず、接続失敗を報告します。設定した認証情報を直すか、OAuthを使いたいならそのヘッダーを外してください。ブラウザーログインを繰り返しても、手動で設定した不正なトークンは直りません。

6. 症状を見てから設定を変える

まずclaude mcp list、次にclaude mcp get <name>を実行します。セッション内なら/mcpを使います。

  • サーバーが設定されていない： localスコープで追加したプロジェクトにいるかを確認します。設定のパスとJSON構文も調べます。不正なエントリーだけが読み飛ばされ、ほかは読み込まれる場合があります。
  • 承認待ち： 設定を確認したうえで、対話セッションでprojectサーバーを承認します。
  • Failed to connect： HTTPステータスやエラー詳細を読みます。getでMCPのパスを含む完全なURLを確認してください。Webサイトに届いてもMCPエンドポイントが正しいとは限りません。
  • Connection error： この状態には詳細が付記されません。HTTPならネットワーク到達性、stdioなら起動コマンドを確認します。
  • 接続済みなのにツールがない： /mcpでツール一覧と必須の環境変数を確認し、Reconnectを選びます。改善しなければclaude --debug=mcpでログを有効にし、~/.claude/debug/以下でサーバーのstderrを調べます。ログ内の秘密情報は共有しないでください。

リモートへの到達性確認には、クイックスタートがcurl -I <url>を案内しています。PowerShellではcurl.exeを使います。404や405でもホストが応答したことは分かり、特にPOSTを想定するエンドポイントでは起こり得ます。ただしMCPのパスやプロトコルの正しさまでは証明しません。401や403なら認証、無応答ならURLとネットワークを調べます。

stdioでは設定済みコマンドと提供元の手順を比べ、必要な実行環境を確認します。commandやargsの相対パスは.mcp.jsonではなく、Claude Codeを起動したディレクトリが基準です。ローカルスクリプトには絶対パスを使います。MCPサーバーを無効にする--safe-modeで起動していないかも確認してください。

起動タイムアウトの既定値は30秒です。初回のnpxダウンロードにはそれ以上かかる場合があります。BashやZshで60秒に延ばすならMCP_TIMEOUT=60000 claude、PowerShellでは$env:MCP_TIMEOUT = "60000"; claudeです。リファレンスのMCP_TIMEOUT=10000 claudeは10秒に設定する例で、既定値ではありません。v2.1.299より前では、稼働中の一部HTTPサーバーが設定に関係なく起動時にタイムアウトしました。該当するならClaude Codeを更新してください。

最初の設定は小さく始める

接続前にサーバーを信頼できるか確認しましょう。外部コンテンツを取得するサーバーにはプロンプトインジェクションのリスクがあります。まず必要なツールを1回呼び出し、権限を確認してからアクセスを広げます。MCPを設定してもClaude Codeの利用上限がなくなるわけではありません。

基本のアクセスができたら、MCP Tasksと作業途中の入力要求は別の段階の参考になります。扱うのは長いジョブの実行中に起きることで、最初のサーバー登録とは異なります。