---
title: "Claude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例【2026年11月】"
url: "https://www.issoh.co.jp/tech/details/19413/"
published: 2026-11-06
updated: 2026-11-06
categories: ["AI"]
publisher: "株式会社一創"
---

# 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との違い](https://www.issoh.co.jp/tech/details/5736/)で、Claude Code自体の導入は[Claude Codeのインストールと初期設定の手順](https://www.issoh.co.jp/tech/details/17375/)で解説しています。ここではインストール済みの前提で、サーバーを登録するコマンドに絞ります。

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

Notion、GitHub、Sentryのように、提供元がURLで公開しているサーバーはHTTPで登録します。[Claude Codeの公式MCPドキュメント](https://code.claude.com/docs/en/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向け導入ガイド](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md)の形で、Windowsで `Invalid input` が返るときは `-H` を使う旧形式が案内されています。PATとOAuthの使い分けは[GitHub Remote MCP Serverの接続手順とPAT・OAuth認証](https://www.issoh.co.jp/tech/details/7271/)が詳しい内容です。

### 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](https://github.com/microsoft/playwright-mcp)にあるサーバーの引数なので、`--` の後ろに付けます。運用までの流れは[Playwright MCPの設定手順](https://www.issoh.co.jp/tech/details/6172/)で解説しました。

### 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クライアント登録の仕組み](https://www.issoh.co.jp/tech/details/10011/)も選択肢になっています。

### 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管理ドキュメント](https://code.claude.com/docs/en/managed-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の権限ルールと管理設定の実装手順](https://www.issoh.co.jp/tech/details/18080/)を参照してください。

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

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

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

## よくある質問（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の違い](https://www.issoh.co.jp/tech/details/6580/)で解説しています。

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

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

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

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

## 関連記事

- [Slack MCPサーバーの接続手順と権限設計｜Claude Code・Codex・Cursorの設定と公式版・OSS版の選び分け](https://www.issoh.co.jp/tech/details/17875/)：OAuthと管理者承認が必要なリモートサーバーをClaude Codeにつなぐ具体例
- [AWS MCP Serverとは？GA版の接続手順と全ツール・権限設計](https://www.issoh.co.jp/tech/details/17726/)：クラウドの操作権限をMCP経由で渡すときのIAM設計
- [Serena MCPとは？仕組み・導入手順とv2の変更点](https://www.issoh.co.jp/tech/details/8197/)：stdioで動くコード解析サーバーをClaude Codeに組み込む手順
- [Claude Desktopとは？Linux対応・料金・インストールとMCP設定の手順](https://www.issoh.co.jp/tech/details/7910/)：デスクトップアプリ側のMCP設定と、Claude Codeへの取り込み元
- [Claude Codeプラグインの作り方と社内配布](https://www.issoh.co.jp/tech/details/17849/)：MCPサーバーをプラグインに同梱して社内へ配る方法
- [Claude Code rulesの書き方｜.claude/rulesのpaths指定とCLAUDE.mdの使い分け](https://www.issoh.co.jp/tech/details/19425/)：CLAUDE.mdと`.claude/rules/`に書く指示の分け方と、pathsで読み込みを絞る設定

---

出典: [Claude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例【2026年11月】](<https://www.issoh.co.jp/tech/details/19413/>)（株式会社一創）