Claude Code MCPの設定手順｜追加・スコープ・接続失敗の直し方

Claude Code MCPの設定は、ターミナルで claude mcp add を実行してサーバーを登録し、claude mcp list で接続状態を確かめる、という2段階が基本です。最初の1台なら claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp を実行し、claude mcp list に ✔ Connected と出れば使える状態です。リモートのサーバーなら claude mcp add --transport http <name> <url>、手元で動かすプログラムなら -- の後ろに起動コマンドを書きます。サーバーの登録先は指定しなければ「local」スコープ（自分だけ・今のプロジェクトだけ）で、チームで共有するときだけ --scope project を付けて .mcp.json に書き出します。つながらないときは、まず claude mcp list の状態表示から切り分けます。

この記事は、公式ドキュメント（Connect Claude Code to tools via MCP と Connect to MCP servers）と2026年10月19日に照合した内容です。版による違いがあり、SSEへの自動切替はv2.1.265以降、Failed to connect へのエラー詳細の表示はv2.1.219以降が必要です。古い版を使っている場合は、先にClaude Codeを更新してください。

Claude Code MCPをつなぐと何が変わるのか

MCP（Model Context Protocol）は、AIと外部ツールをつなぐオープンな標準規格です。MCPのサーバー接続を行うと、Claude Codeが自分のツール、データベース、APIにアクセスできるようになります。

公式のMCP解説は、つなぐ目安を「別のツールからチャットへデータをコピーしている場面」としています。課題管理ツールの内容や監視ダッシュボードの数値を毎回貼り付けているなら、接続すればClaudeがそのシステムを直接読み、操作できます。公式の例には、課題管理ツールに書かれた機能を実装してGitHubにPRを作る、PostgreSQLのデータベースに問い合わせる、といった依頼が並んでいます。

接続できるサーバーはAnthropic Directoryで探せ、掲載されているリモートサーバーは claude mcp add でそのまま追加できます。ただし公式は、接続前にそのサーバーを信頼できるか確かめるよう警告しています。外部のコンテンツを取得するサーバーは、プロンプトインジェクションの危険を持ち込むからです。権限や安全面の設定全体はClaude Codeのセキュリティ設定ガイドに譲り、ここでは接続の手順に絞ります。

最初の1台はどうやって追加し、動作を確かめるのか

公式のクイックスタートが最初の1台に勧めているのは、Claude Codeのドキュメントを全文検索できるホスト型のMCPサーバーです。認証も特別な設定も要らないため、手順の流れだけを確かめられます。以下では、このサーバーで追加から利用・削除までを説明します。

追加は claude セッションの中ではなく、普段のターミナルで実行します。

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

claude-code-docs は自分で決める名前で、ツールのラベルや削除コマンドで使われます。使える文字は英数字・ハイフン・アンダースコアだけで、workspace や computer-use などの組み込みサーバーの予約名は拒否されます。成功すると Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config のような確認と、書き込んだファイルを示す File modified: 行が出ます。

続いて状態を確かめます。

claude mcp list

✔ Connected なら使える状態です。それ以外の表示の読み方は、後半の「つながらないとき」の章にまとめました。個別の詳細は claude mcp get <name> で見られます。

あとは claude でセッションを起動して使います。普段はサーバー名を書かなくてもClaudeが関連するツールを選びますが、接続後の動作確認のときは名前を指定すると、Web取得など別の手段で答えられるのを避けられます。初回の呼び出しで許可を求められたら承認します。出力のツール呼び出しにはサーバー名のラベルが付くので、MCP経由で答えたかどうかはそこで判断できます。

使わなくなったサーバーは削除します。リモートサーバーを削除すると、Claude Codeが保存したそのサーバーのOAuthトークンとクライアント登録も消えます。設定を残したまま止めたいだけなら、削除せずにセッション内の /mcp でオフに切り替えます。

claude mcp remove claude-code-docs

公式によると、接続中のサーバーはツール名や説明がすべてのセッションで読み込まれ、Claudeのコンテキストを消費します。使わないサーバーを外しておけば、その分の余裕を残せます。

HTTP・stdio・SSEのどれで追加すればよいのか

書き方は、サーバーがどこで動いているかで決まります。

ネット上のサーバーには、公式のMCP解説でHTTPが推奨されています。トークンをヘッダーで渡すサーバーには --header を付けます。

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

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

サーバーの説明に streamable-http とあっても同じものです。JSONの type は streamable-http を http の別名として受け付けます。SSEという方式は非推奨で、SSEしか持たないサービスでも、v2.1.265以降は上と同じHTTPのコマンドで追加すればSSEに自動で切り替わります。

手元で動かすプログラムは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

ここでつまずきやすい点が2つあります。1つは --（ハイフン2つ）です。-- より前はClaude Code側のオプション、後ろはサーバーの起動コマンドとしてそのまま渡されます。もう1つは --env の位置で、直後にサーバー名を置くと名前まで KEY=value の組として読まれ、拒否されます。上の例のように、間に --transport stdio などを挟みます。

READMEにJSON形式の設定が載っているサーバーは、claude mcp add-json <name> '<json>' で直接追加できます。WebSocketのサーバーは --transport フラグに対応しないため、この方法か .mcp.json で設定します。JSONで url を書いて type を省くとstdioとして読まれ、設定エラーでスキップされる点に注意してください。

local・project・userのどのスコープに登録すべきか

スコープは「どのプロジェクトで読み込まれるか」と「チームと共有するか」を決めます。

スコープ	読み込まれる範囲	共有	保存先
local（既定）	今のプロジェクトだけ	しない	`~/.claude.json`
project	今のプロジェクトだけ	バージョン管理で共有	プロジェクト直下の `.mcp.json`
user	自分のすべてのプロジェクト	しない	`~/.claude.json`（トップレベルの `mcpServers`）

公式のスコープの説明の基準では、localは個人の開発用サーバー、試験的な設定、バージョン管理に入れたくない認証情報を持つサーバー向けです。userはどのプロジェクトでも使う個人用の道具、projectはチーム全員に同じツールを使わせたいときに選びます。指定は --scope（短縮形 -s）です。

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

MCPの「local」は ~/.claude.json に保存され、一般設定の .claude/settings.local.json とは別物です。settings系ファイルの役割はsettings.jsonの書き方ガイドを参照してください。

同じ名前を複数のスコープに登録したらどうなるか

同じサーバーが複数の場所で定義されていると、Claude Codeは最も優先度の高い定義を1つだけ使います。順位は local、project、user、プラグイン提供のサーバー、claude.aiのコネクタの順です。

見落としやすいのは、フィールドがスコープ間でマージされない点です。projectの定義に headers を足しても、同名のlocal定義があればlocal側がまるごと使われます。「.mcp.json を直したのに反映されない」ときは、まず同名のlocal定義を疑ってください。エンドポイントが異なる同名定義は claude mcp list と /mcp に警告が出るので、不要な方を claude mcp remove <name> --scope <scope> で消します。

スコープは追加時に固定され、後から変えるには削除して追加し直します。どのスコープに入っているかは claude mcp get <name> で確認できます。削除するとリモートサーバーではOAuthトークンとクライアント登録も消えるため、事前に claude mcp get <name> で設定を控え、認証が必要なサーバーは追加し直したあとにサインインし直します。

claude mcp remove claude-code-docs --scope local

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

チームで.mcp.jsonを共有するとき何に気をつけるか

--scope project で追加すると、プロジェクト直下の .mcp.json が作成または更新されます。公式のクイックスタートによると、コミットすれば、クローンしたメンバーがClaude Codeを起動したときに承認のプロンプトが出て、承認後に接続されます。

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

承認プロンプトは何を防いでいるのか

このプロンプトは、クローンしたリポジトリが本人の同意なくマシン上でプロセスを起動するのを防ぐためのものです。リポジトリの .claude/settings.json に enabledMcpjsonServers などをコミットしても、信頼していないフォルダでは無視され、サーバーは ⏸ Pending approval のまま止まります。一度拒否したサーバーを承認し直すときは、承認状態をリセットします。

claude mcp reset-project-choices

例外として、claude -p での実行、Agent SDK、クラウドセッションではプロンプトを出せないため、projectスコープのサーバーは確認なしに読み込まれます。自動実行で読ませたくないサーバーは、設定の disabledMcpjsonServers に書けばどの権限モードでもブロックされます。--strict-mcp-config で起動して --mcp-config で渡したサーバーだけを使う方法もあります。

APIキーを.mcp.jsonに書かずに共有するには

.mcp.json は環境変数の展開に対応しています。${VAR} は環境変数 VAR の値に、${VAR:-default} は未設定なら default に置き換わり、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} の文字列のまま使われ、claude mcp list に警告が出ます。

1つ知っておきたい仕様があります。リモートサーバーの url と headers では、ANTHROPIC_API_KEY や ANTHROPIC_AUTH_TOKEN などClaude Code自身やクラウドプロバイダの認証情報の変数は、設定済みでも空として扱われます。.mcp.json やプラグインがこれらを外部サーバーへ送るのを防ぐためで、サーバーには Bearer だけが届き、多くは 401 で接続失敗になります。どうしても渡したい値は、別名の変数にコピーしてその名前を参照します。

MCPの設定をチーム全体に広げる場合は、社内での承認の取り方もあわせて整理しておくと進めやすくなります。進め方はClaude Code導入における社内稟議の進め方にまとめています。

認証が必要なリモートサーバーはどうつなぐのか

多くのクラウド型MCPサーバーは認証を求めます。公式のMCP解説によると、Claude CodeはOAuth 2.0に対応していて、サーバーを追加したらセッション内で /mcp を実行し、ブラウザでログインします。

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

/mcp

トークンは安全に保存され、自動で更新されます。取り消すときは /mcp のメニューの「Clear authentication」を選びます。ブラウザが開かなければ、表示されたURLを手動で開きます。セッションを開かずに、シェルから認証することもできます。

claude mcp login sentry

保存した認証情報は claude mcp logout <name> で消せます。claude -p やAgent SDKの実行には /mcp の画面がなくOAuthのフローを実行できないため、自動化で使うサーバーは先に対話セッションか claude mcp login でサインインを済ませておきます。

--header で Authorization を設定していてサーバーがそれを拒否した場合、OAuthには切り替わらず接続失敗になります。トークンがそのエンドポイントで有効か確かめるか、ヘッダーを外してOAuthで認証してください。GitHubやNotionなど個別サービスの接続は、GitHub連携ガイドやNotion連携ガイドで扱っています。

つながらないときはどこから確認すればよいのか

公式のトラブルシューティングに沿うと、最初に見るのは状態表示です。シェルなら claude mcp list、セッション内なら /mcp で確認します。失敗時の表示はlistコマンドの失敗ではなく、接続トラブルでそのサーバーに接続できなかったという意味です。

状態表示	意味と次の一手
`✔ Connected`	使える状態
`! Connected · tools fetch failed`	接続したがツール一覧を取れない。`claude mcp get <name>` で詳細を見る
`! Needs authentication`	届いているが、ブラウザでのサインインか `--header` のトークンが必要
`✘ Failed to connect`	サーバーが応答しなかった
`✘ Connection error`	接続の試行中にエラーが起きた
`⏸ Pending approval`	未承認のprojectスコープのサーバー。`claude` を対話で起動して承認する
`⊘ Disabled for this project`	このプロジェクトで無効にしている。`/mcp` から戻す

サーバーが1つも見つからない

/mcp に「No MCP servers configured」と出る主な原因は3つです。別のプロジェクトで追加した（localはそのプロジェクトに結びつくので、追加し直すか --scope user にする）、違う場所のファイルを編集した（手で編集するなら確認するファイルは ~/.claude.json と <project>/.mcp.json で、~/.claude/mcp.json などは読まれない）、.mcp.json に不正なエントリを書いた（そのエントリだけがスキップされる）、のいずれかです。

Failed to connect / Connection error と出る

Failed to connect には、claude mcp list や claude mcp get <name> に添えられるHTTPステータス、エラーコード、サーバーが返したエラー文を確認します。v2.1.219より前は状態だけが表示されるため、次の確認に進みます。Connection error には詳細が付かないため、次の確認に進みます。トークンを貼り付けたときに末尾の改行などが混ざると警告が出ますが、値は書かれた通りに使われるので、自分で取り除きます。

HTTPサーバーは、自分のマシンからURLに届くかを確かめます。

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

PowerShellでは curl ではなく curl.exe を使います。404 や 405 ならサーバーは動いています。401 や 403 なら認証が必要で、応答がなければURLとネットワークを確認します。

stdioサーバーは、設定した起動コマンドを直接実行します。公式の例はPlaywrightのサーバーです。

npx -y @playwright/mcp@latest

起動して入力待ちになれば本体は正常なので、claude mcp get <name> に表示されるコマンドと一致しているかを見ます。違っていれば -- の書き忘れが濃厚で、claude mcp get <name> の出力を控えてから削除し、-- を入れて追加し直します。v2.1.285より前は、type の無いstdioエントリ（手で書いた .mcp.json など）だと claude mcp get にコマンドが表示されないので、claude mcp list で確かめます。エラーで止まれば、Node.jsなど足りないものがメッセージに出ます。

その他のよくある症状

起動時にタイムアウトする：既定の起動タイムアウトは30秒で、stdioは初回の npx のダウンロードで遅れることがある。MCP_TIMEOUT をミリ秒で指定して延ばす（例：MCP_TIMEOUT=60000 claude。PowerShellでは $env:MCP_TIMEOUT = "60000"; claude）
「already exists」と出る：同じスコープに同名がある。先に削除するか別の名前にし、複数スコープにあるなら --scope で消す側を指定する。削除するとリモートサーバーではOAuthトークンとクライアント登録も消えるので、残したい設定なら別の名前で追加する
接続できたのにツールが出ない：APIキーなど必要な環境変数の不足が多い。--env KEY=value か .mcp.json の env で渡す
.mcp.json の変更が反映されない：読み込みはセッション開始時なので、起動し直す。以前拒否したなら claude mcp reset-project-choices を実行する
ツールの出力が大きすぎる：1万トークン超で警告が出て、既定の上限は2万5,000トークン。上限は MAX_MCP_OUTPUT_TOKENS で変えられる

プラグインに同梱されたMCPサーバーの扱いはClaude Codeのプラグインガイドで扱っています。