AI

Claude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例【2026年11月】

Claude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例【2026年11月】

Claude CodeにMCPサーバーを足す方法は、claude mcp add コマンドで登録するか、プロジェクト直下の .mcp.json に書くかの2通りです。この記事では、登録コマンド、3つのスコープの保存先と優先順位、チームで共有する .mcp.json の書き方を実行例つきで整理します。後半はOAuth接続、コンテキスト消費の抑え方、組織で接続先を絞る managed-mcp.json まで扱います。基準はClaude Code 2.1.318（2026年11月6日時点のnpm最新）です。

まとめ：Claude CodeにMCPサーバーを追加する前に決めるスコープと認証方式

個人で試すだけなら、claude mcp add を既定のlocalスコープで実行すれば足ります。設定は自分のホームの ~/.claude.json に入り、リポジトリには何も残りません。チーム全員に同じサーバーを使わせたいときだけ --scope project を付け、生成される .mcp.json をコミットします。

認証は、OAuthに対応したリモートサーバーなら /mcp からブラウザでログインし、トークンを設定ファイルに書かないのが基本です。APIキーしか使えないサーバーは ${API_KEY} の環境変数展開で値を外に出します。会社として接続先を絞る段階になったら、managed-mcp.json か許可リストで管理側から縛り、名前ではなくURLとコマンドで照合させてください。

claude mcp addでHTTPとstdioのMCPサーバーを登録する手順

MCPの仕組みそのものはMCPの仕組みとAPIとの違いで、Claude Code自体の導入はClaude Codeのインストールと初期設定の手順で解説しています。ここではインストール済みの前提で、サーバーを登録するコマンドに絞ります。

リモートMCPサーバーを–transport httpで追加する手順とヘッダー認証

Notion、GitHub、Sentryのように、提供元がURLで公開しているサーバーはHTTPで登録します。Claude Codeの公式MCPドキュメントは、SSEを非推奨としてHTTPを推奨しています。v2.1.265以降は --transport http でまずHTTPを試し、受け付けられなければSSEへ自動で切り替わるため、迷ったらhttpを指定してかまいません。

# OAuth対応のリモートサーバー（認証は後で /mcp から行う）
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"

# GitHub公式のリモートサーバーをJSONで一括登録（Claude Code 2.1.1以降）
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'

GitHubの例はGitHub MCP ServerのClaude向け導入ガイドの形で、Windowsで Invalid input が返るときは -H を使う旧形式が案内されています。PATとOAuthの使い分けはGitHub Remote MCP Serverの接続手順とPAT・OAuth認証が詳しい内容です。

npxで動くstdioサーバーを追加するときの「–」区切りと–envの位置

手元のプロセスとして起動するstdioサーバーは、-- の前にClaude Code側のオプション、後ろにサーバーの起動コマンドを書きます。-- より後ろは一切解釈されず、そのままサーバーへ渡されます。

# Playwright MCP（README記載の形。2026-11-06時点の最新は0.0.84）
claude mcp add playwright npx @playwright/mcp@latest

# 環境変数を渡すstdioサーバー。--env の直後にサーバー名を置かない
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

つまずきやすいのは --env の位置です。--env は複数の KEY=value を受け取るため、直後にサーバー名を置くと名前まで環境変数と解釈され、登録が拒否されます。上の例のように --transport stdio を間に挟む方法で回避できる仕様です。Playwright側の --headless や --isolated はmicrosoft/playwright-mcpのREADMEにあるサーバーの引数なので、-- の後ろに付けます。運用までの流れはPlaywright MCPの設定手順で解説しました。

claude mcp listの接続状態表示と/mcpでの認証・一時無効化の操作

登録後は claude mcp list で状態を確かめます。サーバーごとに ✔ Connected、! Needs authentication、✘ Failed to connect のいずれかが付き、承認前のプロジェクト設定は ⏸ Pending approval と出ます。個別の定義は claude mcp get <name>、削除は claude mcp remove <name> です。

セッション内では /mcp パネルからログイン、設定を残したままの一時的なオフ、全サーバーの再接続（v2.1.284以降は /mcp reconnect all）を行えます。

local・project・userの3スコープの保存先と同名サーバーの優先順位

claude mcp add に --scope を付けないと、localスコープとして登録されます。どこに保存され、誰に見えるかはスコープで決まります。

local・project・userのスコープ別に保存先と共有範囲を比べる早見表

スコープ 読み込まれる範囲 保存先 チーム共有
local（既定） そのプロジェクトのみ ~/.claude.json 内 しない
project そのプロジェクトのみ プロジェクト直下の .mcp.json Gitで共有
user すべてのプロジェクト ~/.claude.json しない

使い分けの目安は単純です。個人のAPIキーを使う検証用はlocal、どのリポジトリでも使う汎用ツール（ドキュメント検索など）はuser、リポジトリの開発に必須でチームの全員が使うものだけproject、と分けます。.mcp.json はコミットされるため、トークンの実値は書きません。

同名サーバーはlocalが勝つ優先順位とフィールドが混ざらない仕様

同じ名前のサーバーが複数の場所に定義されていると、local、project、user、プラグイン提供、claude.aiのコネクターの順で上位の定義だけが使われます。組織が managedMcpServers（v2.1.259以降）で配ったサーバーはさらにその上です。

見落としやすいのは、フィールド単位のマージが起きない点です。たとえばprojectの .mcp.json にURLとヘッダーを書き、自分のlocalに同名で別のURLだけを登録すると、localの定義がまるごと採用され、projectのヘッダーは引き継がれません。チームの設定が効かないときは、claude mcp get <name> で使われている定義を確かめ、古いlocal登録を claude mcp remove <name> --scope local で消します。

チームで共有する.mcp.jsonの設定例と環境変数でトークンを外に出す書き方

.mcp.json は claude mcp add --scope project で生成させても、手で書いてもかまいません。

GitHubとPlaywrightを並べた.mcp.jsonの実例と各フィールドの意味

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--isolated"]
    },
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_MCP_URL:-https://mcp.internal.example.com}/mcp",
      "timeout": 600000
    }
  }
}

リモートは type と url、stdioは command と args が骨格です。timeout はそのサーバーのツール呼び出しの上限をミリ秒で書く項目で、1000未満の値は無視されます。type には ws（WebSocket）も書けますが、claude mcp add --transport は ws を受け付けないため、WebSocketのサーバーはこのファイルか add-json でしか登録できません。

${VAR:-default}展開が効く5つのフィールドと空文字が既定値を潰す落とし穴

環境変数の展開は ${VAR} と、未設定時の既定値を付ける ${VAR:-default} の2形式です。展開されるのは command、args、env、url、headers の5か所に限られます。

落とし穴は2つあります。1つ目は、空文字が入った変数は「設定済み」と扱われ、:-default が効かないことです。既定値を使わせたいなら、空にするのではなく変数自体を消します。2つ目は、リモートサーバーの url と headers では、ANTHROPIC_API_KEY や AWS_BEARER_TOKEN_BEDROCK、NPM_TOKEN などClaude Code自身やクラウドの認証情報が、設定されていても空として読まれる仕様です。手元の鍵が外部へ送られないための措置なので、MCP用には専用の変数名を用意してください。

未設定で既定値も無い変数は、claude mcp list に警告が出たうえで ${VAR} という文字列のまま送られます。

初回起動時の承認ダイアログとclaude -pでは確認なしで読み込まれる点

対話モードでは、.mcp.json のサーバーを使う前に承認を求められ、選択は claude mcp reset-project-choices で取り消せます。信頼していないフォルダーだと、プロジェクトの .claude/settings.json に enableAllProjectMcpServers を書いても無視されるため、クローンしただけのリポジトリが自分を承認することはできません。

注意したいのは逆側です。claude -p、Agent SDK、プロジェクト外のクラウドセッションは承認ダイアログを出せず、.mcp.json のサーバーを確認なしで読み込みます。CIで外部のリポジトリを扱うなら、--strict-mcp-config と --mcp-config で渡したサーバーだけに限定しましょう。

# CIでは .mcp.json を読ませず、指定した設定ファイルのサーバーだけを使う
claude -p "テストの失敗原因を調べて" \
  --strict-mcp-config --mcp-config ./ci-mcp.json

OAuth必須のリモートMCPサーバーへ接続するときのコールバックと事前登録

SaaSのリモートサーバーの多くはOAuthで利用者本人として認可し、トークンを設定ファイルに書かずに済みます。

/mcpとclaude mcp loginでのブラウザ認証とブラウザが無い環境の手順

対話セッションでは /mcp を開き、対象のサーバーを選ぶとブラウザでログイン画面が開きます。シェルからは claude mcp login <name>、解除は claude mcp logout <name> です。SSH先などブラウザが無い環境ではURLが表示されるので、手元のブラウザで開き、リダイレクト先のURLを貼り戻します。--no-browser を付ければ、ブラウザがある環境でもこの手順に固定できます。

v2.1.299以降は、OAuthのログイン時にも設定した headers が送られます。X-API-Key を要求するゲートウェイの奥にサーバーがある構成で、ログインだけ失敗していた場合はバージョンを確認してください。

–client-idと–callback-portで事前登録アプリにつなぐ

動的クライアント登録に対応していないサーバーでは、管理者が事前に登録したOAuthアプリのクライアントIDを使います。リダイレクトURIは http://localhost:PORT/callback の形で登録し、同じポートを --callback-port で固定します。

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

# CIなど対話できない環境ではシークレットを環境変数で渡す
MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

--client-secret は値を引数に取らず、マスクされた入力欄で聞かれます。これらのフラグが有効なのはHTTPとSSEだけです。クライアントIDの登録方式は、DCRに代わるCIMDによるOAuthクライアント登録の仕組みも選択肢になっています。

headersHelperで短命トークンを接続ごとに発行する社内ゲートウェイ構成

社内の認証基盤が短命トークンを発行する構成では、headersHelper に任意のコマンドを指定し、接続のたびにヘッダーを作らせます。コマンドは標準出力に文字列のキーと値だけのJSONを返します。

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

仕様上の数字は3つ押さえれば足ります。実行のタイムアウトは10秒。headers と同名のヘッダーはヘルパーの値で上書きされます。応答が401か403の場合は、ヘルパーを再実行したうえで1回だけ再試行する仕様です。リポジトリやプラグインが持ち込んだヘルパーは認証情報の変数を除いた環境で動くので、鍵を環境変数から読むヘルパーはuserかlocalに置きます。

MCPサーバーを増やしすぎたときのコンテキスト消費とタイムアウトの調整

サーバーを足すほど、ツール定義と応答が会話の容量を圧迫します。

ツール定義を後から読み込むツール検索とENABLE_TOOL_SEARCHの切り替え

Claude Codeは、セッション開始時にMCPツールの名前とサーバーの説明だけを読み込み、定義本体は必要になった時点で検索して取り込みます。この仕組みは既定で有効で、対象はClaude Opus 4、Sonnet 4、Haiku 4.5以降のモデルです。サーバーごとのツール数に固定の上限はありません。

# 定義の合計がコンテキストの10%未満なら先読みし、超えたら検索に切り替える
ENABLE_TOOL_SEARCH=auto claude

# しきい値を5%に下げる
ENABLE_TOOL_SEARCH=auto:5 claude

# 検索を使わず、全ツールを最初から読み込む
ENABLE_TOOL_SEARCH=false claude

毎ターン使うツールだけは、サーバーの設定に "alwaysLoad": true を書いて常に読み込ませます。全部に付けると検索の意味が無くなるため、1〜2サーバーに留めます。

応答上限MAX_MCP_OUTPUT_TOKENSと起動待ちMCP_TIMEOUTの調整

MCPツールの応答の上限は既定で25,000トークンです。10,000トークンを超えると警告が出て、テキストの結果が50,000文字を超えるとファイルに保存されます。データベース系のサーバーでは MAX_MCP_OUTPUT_TOKENS=50000 のように上げられますが、そのぶん会話の容量が減ります。

起動待ちは MCP_TIMEOUT（MCP_TIMEOUT=10000 claude で10秒）、ツール呼び出しは MCP_TOOL_TIMEOUT で未設定時は約28時間、無通信で切る時間はHTTP・SSE・WebSocketが5分、stdioが30分です。初回の npx の取得待ちで接続に失敗するなら、MCP_TIMEOUT を延ばしてください。

組織でMCP接続を許可制にするmanaged-mcp.jsonと許可リスト

既定では、Claude Codeの利用者は好きなMCPサーバーを追加できます。組織向けのMCP管理ドキュメントは、AnthropicがMCPサーバーのセキュリティ監査をしていないと明記しており、業務端末ではどこまで縛るかを管理側で決めることになります。

managed-mcp.jsonで接続先を固定する方式とOS別の配置パス

最も強い方式は、管理者権限でしか書けないシステムパスに managed-mcp.json を置くことです。置かれている端末では、このファイルのサーバーだけが読み込まれ、利用者の追加やプラグイン提供のサーバー、--mcp-config は使えなくなります。

  • macOS：/Library/Application Support/ClaudeCode/managed-mcp.json
  • LinuxとWSL：/etc/claude-code/managed-mcp.json
  • Windows：C:\Program Files\ClaudeCode\managed-mcp.json

書式は .mcp.json と同じです。"mcpServers": {} と空にすればMCPを実質的に止められます。端末の全ユーザーが読めるファイルなので、env にAPIキーを書かず、${VAR} 展開かOAuthで利用者ごとに認証させる運用です。効いているかは、claude mcp add --transport http test https://example.com/mcp が enterprise MCP configuration is active で拒否されるかで確かめられます。

許可リストをserverNameでなくURLとコマンドで書く理由

接続先を固定せず、承認済みの一覧から利用者に選ばせる方式もあります。管理設定に許可リストと拒否リストを書き、allowManagedMcpServersOnly を true にすると、利用者が自分の設定で許可を広げられなくなります。

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" },
    { "serverCommand": ["npx", "@playwright/mcp@latest", "--isolated"] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

serverName での照合は統制になりません。名前は利用者が claude mcp add で好きに付けるラベルなので、どんなサーバーでも github と名乗れます。公式ドキュメントにも警告として明記されている内容です。リモートは serverUrl、stdioは serverCommand で書き、コマンドは引数の順番まで完全一致で照合される点に注意します。拒否リストに一致したサーバーは、許可リストに載っていても読み込まれません。

もう1つの落とし穴は、allowedMcpServers を書かない状態と空配列 [] の違いです。書かなければ全サーバーが許可、空配列なら全サーバーが不許可になります。権限ルールやサンドボックスを含めた管理設定の全体像はClaude Codeの権限ルールと管理設定の実装手順を参照してください。

個人の.mcp.jsonで足りる場面と許可リスト運用へ切り替える判断基準

開発者が数人で、接続先がドキュメント検索やローカルのブラウザ操作に限られ、社内データに触れないなら、projectスコープの .mcp.json をレビューして共有するだけで十分です。この段階で managed-mcp.json を配ると、検証のたびに管理者の作業が挟まります。

切り替えの条件は2つです。顧客情報や基幹システムに書き込めるツールを持つサーバーを1つでもつなぐこと。または、利用者が20人を超えて各自の ~/.claude.json を誰も把握できなくなったことです。どちらかに当てはまったら、許可リストを serverUrl と serverCommand で書き、社内APIは自前のMCPサーバーとして認可を組み込んだうえで公開します。社内システムをMCPでAIエージェントに接続する設計・実装は、AIエージェント開発の受託サービスで要件整理から相談を受けています。

よくある質問（Claude CodeのMCP設定でつまずきやすい点）

MCPサーバーの登録と読み込みで、検索されることの多い質問をまとめました。

Claude DesktopのMCP設定をClaude Codeに移せますか？

macOSとWSLなら移せます。claude mcp add-from-claude-desktop を実行すると、Claude Desktopに登録済みのサーバーが一覧で表示され、取り込むものを選べます。全プロジェクトで使う場合に付けるのは --scope user です。名前に英数字・ハイフン・アンダースコア以外（空白など）を含むサーバーは取り込まれず、同名が既にあれば server_1 のように番号が付きます。取り込みは複製なので、後からDesktop側を変えても反映されません。

.mcp.jsonを置いたのにサーバーが読み込まれないのはなぜですか？

多いのは承認待ちのケースです。claude mcp list で ⏸ Pending approval と出ていれば、対話モードの claude を起動して承認します。過去に拒否した選択が残っているなら claude mcp reset-project-choices で戻せます。次に疑うのは同名のlocal登録で、localはprojectより優先されるため、claude mcp get <name> でどの定義が使われているかを確認してください。

SSEのMCPサーバーはまだ使えますか？

使えますが非推奨です。公式ドキュメントはHTTP（Streamable HTTP）を推奨しており、v2.1.265以降は --transport http で登録しておけば、HTTPを受け付けないサーバーには自動でSSEで接続します。2つの方式の違いはStreamable HTTPとSSEの違いで解説しています。

MCPサーバーのプロンプトやリソースはどう呼び出しますか？

サーバーが公開するプロンプトはスラッシュコマンドになり、/ を打つと /servername:promptname (MCP) の形で候補に並びます。/mcp__github__list_prs のように直接打つ方法でも実行が可能です。リソースは @github:issue://123 のように「@サーバー名:プロトコル://パス」で参照します。

Claude Code自体をMCPサーバーとして使えますか？

使えます。claude mcp serve でClaude CodeがstdioのMCPサーバーとして起動し、Claude Desktopなど別のクライアントからファイル編集やコマンド実行のツールを呼べるようになります。起動しても何も表示されないのが正常です。公開されるのはツールだけで、ツール呼び出しごとの確認はクライアント側の実装に任される点に注意してください。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.05　テックブログ Linuxカーネルの脆弱性CVE-2026-98432：修正版の見分け方とnftablesの緩和策
  2. 2026.11.05　テックブログ SMBCコンシューマーファイナンスの情報漏洩：最大32万人の対象確認と保証会社に集まる情報
  3. 2026.11.03　テックブログ クラブツーリズム不正アクセス：約432万件の対象確認と偽メールの見分け方・流出検知の設計
  4. 2026.10.29　テックブログ ソニー生命の情報漏洩38.5万件｜ログインできない理由、再開状況と窓口の電話番号
  5. 2026.11.05　コラム 給与支払報告書とは？令和8年分の提出期限・書き方と源泉徴収票みなし提出への対応

RELATED POSTS 関連記事

一覧へ戻る

目次