Claude CodeのMCP設定方法|追加コマンド・設定ファイルの場所・スコープ・確認を実機で検証
Claude CodeにMCPサーバーを追加する方法を、claude mcp add の書き方、設定ファイル(~/.claude.json・.mcp.json)の場所、3つのスコープ、claude mcp list での確認まで実機で解説。Claude Code 2.1.319で33回のコマンドと12回の接続テストを行い、よくある失敗のエラー文と直し方、環境変数の展開、承認の注意点を確かめました。

Claude CodeのMCP設定は、ターミナルで claude mcp add <名前> -- <起動コマンド> を実行し、claude mcp list で「✔ Connected」と出るかを確かめるのが基本です。編集部が2026年11月9日にClaude Code 2.1.319で試したところ、設定の保存先はスコープ(使える範囲)によって3か所に分かれ、同じ名前を3か所に置くと12回中12回「ローカル」の設定が使われました。一方で、サーバーのパスを打ち間違えても追加は成功扱いになり、警告は出ませんでした。
MCP(Model Context Protocol)とは、AIアプリに外部のデータや機能を「ツール」として渡すための公開の標準です。MCPサーバーは、そのツールを提供するプログラムです。Claude Codeに追加すると、Claudeが作業中にそのツールを呼び出せるようになります。
本記事は、Claude Code側の「設定」に絞った解説です。MCPサーバーそのものの作り方はMCPサーバーの作り方(TypeScriptで自作しCodexにつないだ検証)、Claude Codeの料金はClaude Codeの料金にまとめています。仕組みの説明は Claude Code 公式ドキュメント(2026年11月9日確認)にもとづき、エラー文や保存先はすべて編集部の環境で実際に出たものです。
結論:MCP設定の早見表
MCPサーバーの追加・確認・削除は、すべて claude mcp コマンドで行えます。下の表は、編集部が実際に実行して確かめたコマンドと結果です(2026年11月9日、Claude Code 2.1.319)。
| やりたいこと | コマンド | 実機で確かめたこと |
|---|---|---|
| 自分だけ・このフォルダだけで使う(既定) | claude mcp add 名前 -- コマンド |
~/.claude.json の、そのフォルダの項目に保存された |
| チームで共有する | claude mcp add --scope project 名前 -- コマンド |
プロジェクト直下に .mcp.json が作られた。初回は承認が必要 |
| 全フォルダで使う | claude mcp add --scope user 名前 -- コマンド |
~/.claude.json の直下に保存された |
| JSONの設定をそのまま入れる | claude mcp add-json 名前 '{"command":…}' |
成功。URLだけで type がない設定はエラー |
| 一覧と接続状態を見る | claude mcp list |
✔ Connected/⏸ Pending approval/✘ Failed to connect と、設定の警告が出た |
| 1つの詳細を見る | claude mcp get 名前 |
スコープ・状態・失敗の理由(Issue)が出た |
| 削除する | claude mcp remove 名前 -s スコープ |
Removed MCP server … from local config と出て、設定が消えた |
| Claude Codeの中で確かめる | /mcp |
スコープ別に、接続状態とツールの数が出た |
確認日:2026-11-09。
Claude CodeのMCPとは(1分で)
Claude CodeのMCPとは、Claude Codeに外部のツールをつなぐ仕組みです。たとえば GitHub・データベース・ブラウザ操作・社内の文書検索などのMCPサーバーを追加すると、Claudeがそれらを自分で呼び出して作業できます。
要点は次の3つです。
- つなぎ方は2種類:手元で起動するプログラム(stdio)と、ネット上のサーバー(HTTP)。公式ドキュメントはこのほか SSE・WebSocket も挙げています。
- 設定の置き場所(スコープ)が3つ:ローカル・プロジェクト・ユーザー。どこに置くかで、使える範囲と共有のしかたが変わります。
- プロジェクトの設定は承認が必要:リポジトリに入っている
.mcp.jsonは、他人が書いたコマンドを動かすことになるため、対話モードでは初回に確認画面が出ます。
検証した環境と方法
検証はすべて2026年11月9日 14時08分〜14時16分(日本時間)に行いました。
- Claude Code 2.1.319(サブスクリプションでログイン)、Node.js v24.22.1、Linux。
- 検証用のMCPサーバーを自作しました(
@modelcontextprotocol/server2.4.0)。ツールは1つで、呼ばれると「どの設定から起動されたか」と、受け取った環境変数の値を返し、同じ内容をサーバー側のファイルにも記録します。AIの回答と、サーバーが実際に返した値を突き合わせるためです。 - 普段の設定を汚さないよう、専用のホームフォルダを用意して実行しました。
- 内訳は、
claude mcpなどのコマンド33回、claude -p(対話なしで1回だけ実行するモード)での接続テスト12回、対話モードでの承認画面の確認1回です。接続テストのモデルは Claude Haiku 5.5 です。
以下のコマンドの出力は、実際に表示された文字をそのまま載せています。長いフォルダのパスだけ「…」に省略しました。
Claude CodeにMCPサーバーを追加する手順(5ステップ)
手元で起動する(stdio の)MCPサーバーを追加し、使えるようになるまでの手順です。ネット上のサーバーの場合は、手順2のコマンドが claude mcp add --transport http 名前 URL になります。
1. Claude Codeのバージョンを確かめる
ターミナルで claude --version を実行します。MCPまわりの動きはバージョンで変わることがあるため、記事や公式ドキュメントと照らすときに使います。編集部の環境では 2.1.319 (Claude Code) でした。
2. claude mcp add でサーバーを追加する
使いたいフォルダに移動し、claude mcp add 名前 -- 起動コマンド を実行します。-- より後ろは、そのままサーバーの起動コマンドとして渡されます。APIキーなどを渡すときは --env キー=値 を付け、名前との間に --transport stdio などを1つ挟みます。
3. スコープを決める
自分だけで試すなら既定(ローカル)のままで構いません。チームで共有するなら --scope project、すべてのフォルダで使うなら --scope user を付けます。違いは次の節の表を見てください。
4. claude mcp list で接続を確かめる
claude mcp list を実行し、追加したサーバーの横に ✔ Connected と出ることを確かめます。✘ Failed to connect のときは、claude mcp get 名前 の Issue: の行に理由が出ます。
5. Claude Codeを起動して /mcp で確かめる
claude を起動し、/mcp と入力します。サーバーごとに接続状態とツールの数が出ます。プロジェクトのサーバー(.mcp.json)は、ここで初めて承認の画面が出ます。
実際に3つのスコープで追加したときの出力です。
$ claude mcp add probe-local -- node …/mcp/probe.ts local
Added stdio MCP server probe-local with command: node …/mcp/probe.ts local to local config
File modified: …/home/.claude.json [project: …/proj]
$ claude mcp add --scope project probe-project -- node …/mcp/probe.ts project
Added stdio MCP server probe-project with command: node …/mcp/probe.ts project to project config
File modified: …/proj/.mcp.json
$ claude mcp list
Checking MCP server health…
probe-user: node …/mcp/probe.ts user - ✔ Connected
probe-project: node …/mcp/probe.ts project - ⏸ Pending approval (run `claude` to approve)
probe-local: node …/mcp/probe.ts local - ✔ Connected
プロジェクトのサーバーだけが「⏸ Pending approval(承認待ち)」になっています。これは故障ではなく、まだ承認していないという意味です。
設定ファイルの場所とスコープの違い
MCPの設定ファイルは、ローカルとユーザーのスコープが ~/.claude.json、プロジェクトのスコープがプロジェクト直下の .mcp.json です。.claude/ フォルダの中ではない点に注意してください。
| スコープ | 付けるオプション | 保存先(実測) | 使える範囲 | 向いている用途 |
|---|---|---|---|---|
| ローカル | なし(既定)/--scope local |
~/.claude.json の "projects" → フォルダのパス → mcpServers |
自分だけ・そのフォルダだけ | 試しに入れる、APIキーを含む個人の設定 |
| プロジェクト | --scope project |
プロジェクト直下の .mcp.json |
そのリポジトリを使う全員(承認後) | チームで同じツールを使う |
| ユーザー | --scope user |
~/.claude.json の直下の mcpServers |
自分だけ・すべてのフォルダ | どこでも使う個人用ツール |
確認日:2026-11-09。
実際に .mcp.json に書き込まれた中身は次のとおりです。claude mcp add --scope project を使えば、この形を手で書く必要はありません。
{
"mcpServers": {
"probe-project": {
"type": "stdio",
"command": "node",
"args": [
"…/mcp/probe.ts",
"project"
],
"env": {}
}
}
}
同じ名前を3か所に置くと、ローカルが使われた
同じ名前のサーバーが複数のスコープにあると、Claude Codeは1つだけを使います。公式ドキュメントの優先順位は、ローカル → プロジェクト → ユーザーの順です(設定は混ぜ合わされず、1か所の設定がまるごと使われます)。
編集部が「dup」という同じ名前を3つのスコープに別々の起動コマンドで登録したところ、claude -p の12回すべてでローカルのサーバーが呼ばれました。claude mcp list には次の警告が出ました。
[Conflicting scopes]
├ Server "dup" is defined in multiple scopes with different endpoints: user (node …/mcp/probe.ts dup-user), project (node …/mcp/probe.ts dup-project), local (node …/mcp/probe.ts dup-local). OAuth tokens are stored per endpoint, so authenticating in one context will not carry over.
└ Keep the correct endpoint and remove the others: `claude mcp remove dup -s user` or `claude mcp remove dup -s project` or `claude mcp remove dup -s local`
チームの .mcp.json を直したのに動きが変わらないときは、同じ名前がローカルに残っていないかを claude mcp list で確かめてください。
よくある失敗とエラー文:6つを実際に起こした結果
追加のつまずきは、コマンドの書き方と、サーバーの起動の2つに分かれます。6つを実際に起こし、出たエラー文と直し方をまとめました。
| 失敗 | 出たエラー・状態(実際の表示) | 直し方 |
|---|---|---|
--env の直後に名前を書いた |
Invalid environment variable format: probe-env, environment variables should be added as: -e KEY1=value1 -e KEY2=value2(追加されない) |
--env KEY=値 --transport stdio 名前 -- … のように、間に別のオプションを挟む |
-- を付けずにサーバーのオプションを書いた |
error: unknown option '--port'(追加されない) |
名前の後に -- を入れ、その後ろにサーバーのコマンドを書く |
| 予約された名前(workspace)を使った | Cannot add MCP server "workspace": this name is reserved. |
別の名前にする |
add-json に URL だけを書いた |
Invalid configuration: : Invalid input |
"type":"http" を足す(type がないと手元のプログラムとして扱われる) |
| サーバーのパスを打ち間違えた | 追加は成功(終了コード0、警告なし)。claude mcp list で ✘ Failed to connect — CONNECTION_CLOSED: Connection closed |
追加の後に必ず claude mcp list で確かめ、パスを直して入れ直す |
| 起動に40秒かかるサーバー | ✘ Failed to connect — MCP server "probe-[redacted]" connection timed out after 30000ms |
起動の待ち時間を延ばす(MCP_TIMEOUT=45000 claude で ✔ Connected になった) |
確認日:2026-11-09。
いちばん気づきにくいのは、パスの打ち間違いです。claude mcp add は設定を書き込むだけで、その場でサーバーを起動して確かめるわけではありません。追加したら、毎回 claude mcp list まで実行する習慣にしてください。
起動の待ち時間は、公式ドキュメントでは環境変数 MCP_TIMEOUT(既定30,000ミリ秒=30秒)で変えられるとされています。編集部の実測でも、40秒かかるサーバーは既定のままでは失敗し、MCP_TIMEOUT=45000 では約41秒後に接続できました。起動に3秒かかるサーバーは、既定のままで12回すべて使えました。
つながらないサーバーを、AIは「呼べない」と正直に答えた
パスを間違えたサーバーを残したまま、claude -p で「6つのサーバーのツールを順に呼び、返ってきた文字列をそのまま書いて。呼べないものは理由を書いて」と12回頼みました。12回すべてで、つながらないサーバーを「呼べない(CONNECTION_CLOSED)」と答え、結果を作り話で埋めた回はありませんでした。ほかの5つのサーバーの返り値は、サーバー側の記録(60回分)と12回とも一字一句同じでした。
公式ドキュメントによると、claude -p では、手元のサーバーが最初の接続に失敗するとそのツールなしで実行が続きます。もう一度試すには、実行し直す必要があります。
APIキーは環境変数で渡す:${VAR} の展開を4通り試した結果
.mcp.json には APIキーをそのまま書かず、${変数名} と書いて実行時の環境変数から読み込ませることができます。公式ドキュメントでは ${VAR} と、未設定のときの既定値つきの ${VAR:-既定値} の2つの書き方が使えます。
.mcp.json に次の2つを書き、環境変数 MY_LABEL の状態を変えて、サーバーが実際に受け取った値を記録しました(各3回、claude -p)。
"env": { "PROBE_LABEL": "${MY_LABEL}" }
"env": { "PROBE_LABEL": "${MY_LABEL:-default-label}" }
| MY_LABEL の状態 | ${MY_LABEL} でサーバーが受け取った値 |
${MY_LABEL:-default-label} で受け取った値 |
|---|---|---|
| 未設定 | ${MY_LABEL}(文字のまま)6/6回 |
default-label 6/6回 |
from-shell を設定 |
from-shell 3/3回 |
from-shell 3/3回 |
空の文字(MY_LABEL=) |
空 3/3回 | 空(既定値は使われない)3/3回 |
確認日:2026-11-09。未設定の6回は、承認済み3回と未承認3回の合計です。
未設定のときは claude mcp list に [Warning] [probe-var] mcpServers.probe-var: Missing environment variables: MY_LABEL と出ましたが、サーバーはそのまま起動し、${MY_LABEL} という文字が値として渡りました。APIキーで同じことが起きると、認証エラーになるまで気づきにくいはずです。警告が出ていないかを claude mcp list で確かめてください。空の文字を設定すると既定値が使われない点は、公式ドキュメントの説明どおりでした。
もう1つ注意があります。claude mcp add --env PROBE_LABEL=abc … で渡した値は、claude mcp get を実行すると PROBE_LABEL=abc と、そのまま画面に表示されました。本物のAPIキーを --env で入れると、画面共有やログで見えてしまいます。共有する設定では ${変数名} を使ってください。なお、既定値つきの ${MY_LABEL:-default-label} は、claude mcp get の表示では PROBE_LABEL=${MY_LABEL} となり、既定値の部分は表示されませんでした(実際には既定値が渡っています)。
プロジェクトのMCP(.mcp.json)の承認と、安全上の注意
.mcp.json に書かれたサーバーは、承認するまで使われません。対話モードで初めて起動すると、フォルダを信頼するかの確認のあと、次の画面が出ました。
New MCP server found in this project: probe-team
MCP servers may execute code or access system resources. All tool calls require approval. Learn
more in the MCP documentation.
Use this MCP server
Use this and all future MCP servers in this project
❯ Continue without using this MCP server
Enter to confirm · Esc to cancel
最初に選ばれているのは「Continue without using this MCP server(使わずに続ける)」でした。そのままEnterを押すと、サーバーは使われません。「Use this MCP server」を選ぶと、そのフォルダの .claude/settings.local.json に次のように記録されました。
{
"enabledMcpjsonServers": [
"probe-team"
]
}
承認の後に /mcp を開くと、Project MCPs(…/proj-new/.mcp.json)✔ probe-team 1 tool のように、スコープごとに接続状態とツールの数が表示されました。
claude -p では、未承認の .mcp.json もそのまま読み込まれた
注意が必要なのは、対話なしの claude -p です。承認の記録を外した状態で claude -p を3回実行すると、3回とも確認なしで .mcp.json のサーバーが起動し、ツールが呼ばれました。公式ドキュメントにも、claude -p などでは承認の画面を出せないため、確認せずに読み込むと書かれています。
.mcp.json の command には任意のコマンドを書けます。他人のリポジトリを取ってきて、中身を読まずに claude -p を動かすと、そこに書かれたプログラムが起動することになります。対策は公式ドキュメントに次の3つがあります。
- 使わせたくないサーバー名を、設定の
disabledMcpjsonServersに入れる。 --strict-mcp-configを付けて起動し、--mcp-configで渡したサーバーだけを使う。--setting-sourcesで、プロジェクトの設定を読まないようにする。
AIに外部の文章やツールを渡すときの一般的な危険はプロンプトインジェクションとは、Claude Codeまわりで実際にあった改ざんの事例はClaude Code拡張の改ざん版の配布で解説しています。
自分の設定で承認を済ませる方法
公式ドキュメントでは、リポジトリに含まれる .claude/settings.json の承認は、信頼していないフォルダでは無視されます(取ってきたリポジトリが自分で自分を承認できないようにするため)。一方、自分のホームの ~/.claude/settings.json に "enabledMcpjsonServers": ["サーバー名"] と書く方法は、信頼前のフォルダでも効くとされています。編集部の実測でも、これを書くと claude mcp list の表示が「⏸ Pending approval」から「✔ Connected」に変わりました。権限の allow も同じく信頼前のフォルダでは使われません(settings.jsonの権限設定の実測)。
CLAUDE.mdとの使い分け
MCPは「ツールを渡す」仕組みで、CLAUDE.md は「守ってほしいルールや手順を書く」ファイルです。たとえば「データベースを調べられるようにする」のはMCP、「本番のデータベースには書き込まない」と伝えるのは CLAUDE.md の役割です。CLAUDE.md の置き場所と書き方はCLAUDE.mdの書き方と置き場所、Codex などで使う AGENTS.md はAGENTS.mdとは(CLAUDE.mdとの違い)にまとめています。
Codexでも同じMCPサーバーを使えます。Codexへのつなぎ方(config.toml)はMCPサーバーの作り方、2つのツールの違いはCodexとClaude Codeを比較で説明しています。
まだ確かめていないこと
- ネット上の(HTTP の)MCPサーバーへのログイン(OAuth)と、
/mcpからの認証の流れ。 - Windows・macOS での動き(今回は Linux のみ)。公式ドキュメントには Windows 固有の記載があります。
- VS Code 拡張・デスクトップアプリから見たときの表示。
- Claude Haiku 5.5 以外のモデルでの、つながらないサーバーへの答え方。
- MCPサーバーが増えたときの使用量(トークン)への影響。
社内でAIコーディングツールを入れるかどうか、どの業務から試すかで迷っている場合は、AI活用診断で今の業務に合う使い方を確かめられます。
よくある質問
Q. Claude CodeのMCPの設定ファイルはどこにありますか?
ローカルとユーザーのスコープは、ホームフォルダの ~/.claude.json です。ローカルは "projects" の中のフォルダごとの項目に、ユーザーはファイルの直下に保存されます。プロジェクトのスコープは、プロジェクト直下の .mcp.json です。編集部が Claude Code 2.1.319 で確かめた保存先です。
Q. claude mcp add で追加したのに使えません。どうすればいいですか?
まず claude mcp list を実行し、状態を見てください。✘ Failed to connect ならパスや起動コマンドの誤り、⏸ Pending approval ならプロジェクトのサーバーの承認待ちです。編集部の実測では、パスを打ち間違えても追加は成功扱いで、警告は出ませんでした。
Q. スコープは何を選べばいいですか?
自分で試すだけなら既定のローカル、チームで共有するならプロジェクト(.mcp.json をGitに入れる)、すべてのフォルダで使う個人用ツールならユーザーです。APIキーを含む設定はローカルかユーザーにし、共有する .mcp.json には ${変数名} で書きます。
Q. MCPサーバーが接続できているか確かめる方法は?
ターミナルなら claude mcp list(一覧)か claude mcp get 名前(詳細)、Claude Codeの中なら /mcp です。claude mcp get では、失敗の理由が Issue: の行に出ます。
Q. .mcp.json に APIキーを書いても大丈夫ですか?
共有する .mcp.json には書かず、"${API_KEY}" のように環境変数で渡してください。編集部の実測では、環境変数が未設定だと警告は出るものの、${API_KEY} という文字がそのまま渡りました。--env で直接入れた値は、claude mcp get でそのまま表示されました。
Q. MCPサーバーの起動が遅くてタイムアウトします。
起動の待ち時間は既定で30秒です。MCP_TIMEOUT=45000 claude のように、ミリ秒で延ばせます。編集部の実測では、起動に40秒かかるサーバーが既定では失敗し、45秒に延ばすと接続できました。
確認元(2026-11-09 確認)
仕様は変わることがあるため、最新情報は公式で確認してください。取得日はいずれも2026年11月9日(日本時間)です。
- Connect Claude Code to tools via MCP(Claude Code 公式ドキュメント)(新しいウィンドウで開く)(日本語版(新しいウィンドウで開く)):追加コマンド(
claude mcp add・add-json・list・get・remove)、--と--envの書き方、3つのスコープと優先順位、.mcp.jsonの承認とclaude -pでの扱い、${VAR}の展開、設定の警告、接続失敗時の動き。 - Environment variables(Claude Code 公式ドキュメント)(新しいウィンドウで開く):
MCP_TIMEOUT(起動の待ち時間、既定30,000ミリ秒)、MCP_TOOL_TIMEOUT。 - 設定(Claude Code 公式ドキュメント)(新しいウィンドウで開く):
~/.claude.jsonに MCP サーバーの設定やプロジェクトごとの状態が保存されること。 - 一次データ(本記事の実測):数値データ
data/experiments/2026-11-09-claude-code-mcp-runs.json。実行ログは編集部の環境の/workspace/experiments/site-1109/(コマンド33回・接続テスト12回・承認画面の記録)。


