MCP接続設定はどこに書く？3スコープの選び方と確認の手順

「このMCP、どこに書けばいいんですか」。Claude CodeにMCPサーバーをつなぐ話になると、まずこの質問が出ます。

つなぐ操作そのものは、コマンド1本で終わります。つまずくのはそのあとです。自分の手元では動くのに、同僚の環境では出てこない。書いたはずの設定が一覧に並ばない。原因は書いた中身ではなく、書いた場所にあることが多いです。

MCP（Model Context Protocol）は、AIとツールをつなぐための公開仕様です（出典: MCP公式）。この記事は、接続設定を置ける3つの場所の違い、名前がぶつかったときの決着のつき方、そして通じたかどうかを確かめる手順を扱います。素材はClaude Code公式ドキュメントとMCP公式の記載です。

検証環境：Claude Code公式ドキュメント（code.claude.com/docs、2026-08-03時点の記載）。

進行役は3人です。若葉さんが言葉の側から、高梨課長が自分の手で動かす側から聞き、鈴木さん（本誌監修）が答えます。

01MCPの接続設定って、AIエージェントに何を触らせる作業なんですか？

若葉さん

若葉さんの発言

MCPを設定すると、何ができるようになるんでしょうか。

鈴木さん

鈴木さんの発言

建物に通用口を1つ足すようなものだと思っています。AIがいる部屋から、外のツールやデータベースへ出入りできる口を作る。どの口を開けるかは、こちら側が決めます。

MCPサーバーをClaude Codeへ接続すると、外部のツールやデータベースへ直接アクセスできるようになります。MCPは、AIとツールをつなぐための公開仕様です（出典: MCP公式）。

接続設定と呼んでいるのは、その通用口をどこに書き残すかを決める作業です。書く内容自体は、サーバーの名前と、つなぎ方と、行き先くらいしかありません。分量としては短い設定です。

それでも独立した工程として扱うのは、置き場所が3つあり、どれを選ぶかで「誰の環境で読み込まれるか」が変わるからです。中身がまったく同じでも、置き場所が違えば結果は違います。

02MCPの接続設定は、AIエージェントの共有範囲でどう選び分けるんですか？

置き場所は3つあります。誰と共有するかと、保存先のファイルが違います（出典: Claude Code公式ドキュメント）。

3つを見比べるより、2つの問いに答えるほうが早く決まります。この設定を自分だけが使うのか、チームへ配るのか。そして、このプロジェクトの中だけで効かせたいのか、手元のどのプロジェクトでも効かせたいのか。

置き直すと、表では見えないものが見えます。3つのどれも当たらない区画があることです。バージョン管理で全員へ配り、しかも各自の全プロジェクトで効く、という置き場所は、この3つの中には出てきません。

その位置に近い役割は、3スコープの下に続くプラグイン提供のサーバーやコネクタが担います。この記事は、開発者が自分で書く3つに絞って進めます。

03同じ名前の接続設定がぶつかると、AI社員はどちらを使うんですか？

同じ名前のサーバーが複数の場所に定義されていても、Claude Codeが採用するのは1つだけです。順位は決まっています（出典: 同）。

1. ローカルスコープ
2. プロジェクトスコープ
3. ユーザースコープ
4. プラグイン提供のサーバー
5. claude.aiコネクタ

見落とされやすいのは、順位そのものより決着のつき方です。勝った側の定義が丸ごと採用され、負けた側の同名定義はフィールド単位でも一切引き継がれません（出典: 同）。

キーごとに値を合算していくsettings.jsonの階層とは、仕組みが違います。settings.jsonの感覚のまま「片方に足りない項目は、もう片方から補われる」と読むと、取り違えます。

たとえばdbという名前のサーバーを、ローカルとプロジェクトの両方に別のURLで定義したとします。

このとき動くのはローカルの定義だけです。プロジェクト側に書いたurlもheadersも残りません。

04接続設定を書き始める前に、AI導入の担当者は何を確かめるんですか？

書き始める前に見ておくものが4つあります。

スコープの呼び名は、過去のバージョンで違っていました。いまの「ローカル」は旧称「project」、いまの「ユーザー」は旧称「global」です（出典: 同）。

やっかいなのは、旧称の「project」が、いまの「プロジェクト」とは別のものを指している点です。古い解説を読むときは、呼び名ではなく保存先のファイル名で照合すると取り違えません。

05自分だけが使うMCPは、どのコマンドでAIエージェントに追加するんですか？

--scopeを省略すると、接続設定は既定でローカルスコープへ書き込まれます（出典: 同）。

# 基本形（HTTPサーバー）
claude mcp add --transport http notion https://mcp.notion.com/mcp

このコマンドは、実行したディレクトリのプロジェクトパスに紐づけて~/.claude.jsonへ書き込みます（出典: 同）。

// ~/.claude.json（実行したプロジェクトのpath配下）
{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "notion": {
          "type": "http",
          "url": "https://mcp.notion.com/mcp"
        }
      }
    }
  }
}

手元でプロセスとして動くサーバーは、stdio方式で追加します。起動コマンドと引数は--のあとに書きます。

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

--を書き忘れると、サーバー側のオプションをClaude Code自身のオプションとして誤って解釈します（出典: 同）。--envはKEY=valueの形で、必要な数だけ並べられます。

手元のどのプロジェクトでも同じサーバーを使いたいときは、--scope userを付けます。

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

06チームで配るMCP接続設定は、AI社員を動かす全員にどう届けるんですか？

高梨課長

高梨課長の発言

チーム全員へ同じ設定を配りたいのですが、手順書を回すしかないでしょうか。

鈴木さん

鈴木さんの発言

--scope projectを付けると、リポジトリに乗る形のファイルになります。設定がコードと一緒に配られるので、手順書の更新漏れが起きにくくなります。

高梨課長

高梨課長の発言

受け取った側は、そのまま使える状態になりますか。

鈴木さん

鈴木さんの発言

そこはもう1段あります。配られてくることと、使ってよいと認めることは別に扱われています。

チームで同じ接続設定を使うときは--scope projectを付けます。

claude mcp add --transport http shared-server --scope project https://example.com/mcp

生成される.mcp.jsonはプロジェクトのルートに置かれ、バージョン管理へコミットして配ります（出典: 同）。

// .mcp.json（プロジェクトのルート）
{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

配る形にした時点で、性質が1つ変わります。この中身は、リポジトリを見られる全員の目に触れます。次の章の書き方が要るのは、そのためです。

07APIキーを直に書かずに、AIエージェントのMCP接続設定を配れますか？

配れます。値そのものではなく、値の名前だけを書く方法があります。書式は${VAR}と${VAR:-既定値}の2種類です（出典: 同）。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

展開できる場所はcommand・args・env・url・headersです（出典: 同）。外から渡したい値が入りやすいところが押さえられています。

気をつけたいのは、失敗の見え方です。変数が未設定で既定値も無い場合でも、設定は読み込まれます。展開されなかった${API_KEY}という文字列がそのまま使われ、claude mcp listに警告が出るだけです（出典: 同）。

つまり、エラーで止まってはくれません。認証に失敗した理由を接続先のせいだと思い込むと、警告を見落としたまま時間を使うことになります。

08MCPの接続設定を承認したのに使えないのは、エージェント側の何が原因ですか？

.mcp.jsonに書かれたサーバーは、使う前にClaude Code側の承認を求められます（出典: 同）。書いてある、イコール、すぐ動く、ではありません。

ここで効いてくるのが、承認の記録がどこから読まれるかです。v2.1.196から、この承認はバージョン管理にコミットされていない設定からしか読まれません。対象になるのは、自分のユーザー設定や、信頼済みフォルダの.claude/settings.local.jsonなどです（出典: 同）。

裏返すと、プロジェクトへコミットした.claude/settings.json側に承認を書いても、ワークスペース信頼を通すまでは無視されます。クローン直後のリポジトリは、この意味で自分自身をまだ承認できません（出典: 同）。

承認をやり直したいときはclaude mcp reset-project-choicesを使います。

claude mcp reset-project-choices

09AIエージェントにMCPを繋いだあと、接続設定が効いたかはどこで分かるんですか？

高梨課長

高梨課長の発言

一覧に成功の印が出ていれば、もう使える状態と考えていいでしょうか。

鈴木さん

鈴木さんの発言

そこは分けています。表示が教えてくれるのは「つながった」までで、「呼べた」までは教えてくれません。最後に1回、実際に使う指示を出すところまでを確認に入れています。

設定ファイルを書いただけでは、接続が成立したとは限りません。確かめる入口は3つあります。

# 一覧と簡易ステータス
claude mcp list

# 個別サーバーの詳細
claude mcp get shared-server

# セッション内で対話的に確認する
/mcp

claude mcp listは、サーバーごとに次のいずれかの状態を表示します（出典: 同）。

同じ「使えない」でも、表示が違えば直す場所が違います。認証が残っているのか、そもそも届いていないのか、承認が済んでいないのか。表示は、その仕分けを先にやってくれます。

そのうえで、次の項目を確認します。

• claude mcp listに追加したサーバー名が表示されている
• ステータスが✔ Connectedになっている（OAuthサーバーは/mcpでサインインを済ませたあとに確認する）
• プロジェクトスコープの場合、⏸ Pending approvalのままになっていないか確認した
• そのサーバーのツールを使う指示を実際に出し、外部システムから応答が返ってきた

最後の項目を省かないでください。表示だけを見て終えると、つながっているように見えて、実際には何も呼べていない状態を見逃します。

✘ Failed to connectのまま動かないときは、URLの打ち間違いより先に、認証ヘッダーやAPIキーの環境変数展開を疑うほうが早く着きます。

10MCPの接続設定でAI活用がつまずくのは、どんなところですか？

若葉さん

若葉さんの発言

気をつけるとしたら、どのあたりでしょうか。

鈴木さん

鈴木さんの発言

名前が似ているところです。設定まわりは似た言葉が多いので、別のものを同じだと思ったまま進んでしまうことがあります。

「ローカルスコープ」と.claude/settings.local.jsonを同じものだと思う。MCPのローカルスコープは~/.claude.jsonに保存されます。一般の権限設定が入る.claude/settings.local.jsonとは別のファイルです（出典: 同）。「ローカル」という呼び名は同じでも、指している実体が違います。

環境変数の展開ミスに気づかない。前の章のとおり、未設定でもエラーにはなりません。claude mcp listの警告を見落とすと、止まった原因が分からなくなります。

stdioサーバーの--を忘れる。サーバー起動コマンドの--portのようなオプションを、Claude Code自身のオプションとして解釈させてしまいます。

3つに共通しているのは、どれも設定を書いている画面の中では気づけないことです。書けてしまうし、保存もできてしまいます。おかしいと分かるのは、たいてい動かしてからです。

11MCPの接続設定を許可リストへ載せるとき、生成AIの権限ルールは何が違うんですか？

もう1つ、書けてしまうのに効かない書き方があります。権限ルールでサーバー単位をまとめて許可しようとして失敗する形です。

denyとaskのルールはmcp__*のようにサーバー名を伏せた形も書けますが、allowルールは違います。mcp__<サーバー名>__という具体名のあとにしか、ワイルドカードを置けません（出典: Claude Code公式ドキュメント「Permissions」）。

止める側は広く網を張れて、通す側は名指しでしか書けない、という向きの違いになっています。安全な側へ倒れる作りなので、許可を書くときだけ手数が増えます。

接続したMCPサーバーのツールを許可リストへ載せる書き方は、Claude Codeの権限設定｜AIエージェントに任せる範囲と3列の配分で扱っています。

12よくある質問

13まとめ｜今日やる3つのこと

置き場所は、共有したい範囲から決めました。名前がぶつかったときは、勝った側が丸ごと使われました。そして、書いた設定は呼べるまで確かめない、という順番でした。