ユタラボ
🚀 Claude Code入門

Claude Code MCPの始め方｜増やす前に決める接続境界

Claude CodeへMCPサーバーを追加する前に、ローカルと外部接続、設定スコープ、権限、秘密情報、接続失敗の切り分け方を整理します。

MCPは、Claude Codeから外部の道具やデータへ接続するための共通方式です。便利そうなサーバーを先に増やすのではなく、「何を読ませるか」「どこまで変更させるか」「設定を誰と共有するか」を一つずつ決めると、安全性と直しやすさを両立できます。

この記事では、架空の接続先を使って追加から確認、削除までの流れを説明します。例にあるURLや秘密情報はダミーで、そのままでは接続できません。Claude Codeに作業させるフォルダ自体がまだ曖昧なら、先にClaude Codeにファイルを触らせる基本で範囲を絞ってください。

MCPで増える能力を接続前に言葉にする

MCPサーバーをつなぐと、Claude Codeはそのサーバーが公開するツールやデータを利用できるようになります。たとえば、社内ドキュメントの検索、データベースの参照、課題管理サービスの更新などが候補です。ただし、実際に何ができるかはサーバーごとに異なります。「MCPを入れたから何でもできる」わけではありません。

追加前に、接続の目的を次の形で一文にします。

この接続は、開発用の資料を検索するために使う。更新や削除は許可しない。

目的が「検索」なら、最初から書き込み権限を渡す必要はありません。逆に、課題の作成まで任せたいなら、検索と更新を別の段階として試します。MCPサーバーが取得した外部コンテンツには、Claudeへの命令に見える不正な文章が混じる可能性もあります。Anthropic公式資料も、接続前にサーバーを信頼できるか確認するよう案内しています。

接続先を選ぶ前に確認する項目は、運営者、公開される機能、必要な権限、送信されるデータ、停止方法の五つです。説明が見つからないサーバーは、便利さだけで採用せず「※要確認」として保留します。

ローカル接続と外部接続の違いを押さえる

Claude CodeのMCP接続で最初に理解したいのは、stdioとHTTPの違いです。stdioでは、Claude Codeがパソコン上のMCPサーバーを子プロセスとして起動し、標準入力と標準出力で通信します。ローカルファイルを扱う自作ツールなどに向きますが、起動するプログラム自体が何を読むかは別途確認が必要です。

HTTP接続では、独立して動くサーバーのURLへ通信します。OAuth認証に対応する接続先では、Claude Code内の/mcpからブラウザでログインする流れがあります。パソコンの外へデータが送られる可能性があるため、URL、運営者、利用規約、送信内容を確認してから接続します。

MCPの現行仕様では、標準の通信方式としてstdioとStreamable HTTPが定義されています。以前使われたHTTP+SSEはStreamable HTTPに置き換えられ、Claude Code公式資料でも、利用できる場合はSSEよりHTTPを使うよう案内されています。

「ローカルだから安全」「HTTPだから危険」と単純には分けられません。判断基準は、実行されるプログラムと、そのプログラムが読める範囲、通信先、認証権限です。

最小構成はlocalスコープで一つだけ試す

Claude CodeのMCP設定には、local、project、userの三つのスコープがあります。最初の試行は、現在のプロジェクトだけで自分に見えるlocalが扱いやすい選択です。projectはプロジェクト直下の.mcp.jsonへ保存され、チームで共有できます。userは自分の全プロジェクトで利用できます。

スコープ読み込まれる範囲チーム共有主な用途
local現在のプロジェクトだけしない個人の試用、秘密情報を含む接続
project現在のプロジェクトだけ.mcp.jsonを通じて共有チーム共通の接続定義
user自分の全プロジェクトしない複数案件で使う個人用ツール

localとuserの設定はどちらも~/.claude.jsonに保存されますが、読み込まれる範囲が異なります。チームへ配る必要がない試用設定を、最初からprojectへ置く必要はありません。

次は、架空のHTTPサーバーをlocalスコープへ追加する形です。example.comは説明用であり、実際のMCP接続先ではありません。

claude mcp add --transport http --scope local example \
  https://mcp.example.com/mcp

追加後は、すぐ仕事を頼まず、設定と接続状態だけを確認します。

claude mcp list
claude mcp get example

Claude Codeを対話モードで開いている場合は、/mcpでも状態を確認できます。確認する順番は「一覧に名前がある」「接続先が意図したURLである」「接続済みである」「公開されたツールが想定どおりである」です。最後に、読み取りだけの小さな依頼を一回試します。

プロジェクト共通の指示と、その場の依頼をどう分けるかはClaude Codeへの指示のコツも参考になります。MCPの役割まで長い依頼文へ毎回書くのではなく、接続境界だけを短く固定すると見直しやすくなります。

権限と秘密情報は設定から分離する

APIキーやアクセストークンを.mcp.jsonへ直接書いてGitへ登録すると、接続設定と秘密情報が一緒に共有されます。プロジェクト設定では環境変数を参照し、実際の値は各自の安全な保管場所から渡します。

次は構造を示すためのダミー例です。URL、変数名、トークンは架空です。

{
  "mcpServers": {
    "example-docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${EXAMPLE_MCP_TOKEN}"
      }
    }
  }
}

Claude Code公式資料では、.mcp.jsonのcommand、args、env、url、headersで${VAR}形式の環境変数展開が使えます。必要な変数が未設定で既定値もない場合は、設定の解析に失敗します。この失敗は秘密を直書きして避けるのではなく、環境変数が現在の起動環境へ渡っているか確認します。

チーム共有の.mcp.jsonは、利用前に承認を求める仕組みがあります。ただし、承認画面はサーバーの安全性を保証するものではありません。読取専用の認証情報を発行できるなら、最初はそれを使います。書き込み、削除、公開、課金につながる権限は、動作確認と同時に渡さず、必要性を確認してから追加します。

MCPツール単位の許可は、Claude Codeのpermissions.allow、permissions.ask、permissions.denyで調整できます。評価順はdeny、ask、allowです。接続先の権限とClaude Code側の許可は別の層なので、片方だけを狭めれば十分とは限りません。秘密情報の置き場所はAIコーディングの秘密情報管理、許可ルールの考え方はClaude Codeの権限設定で詳しく整理しています。

接続失敗は四段階で切り分ける

つながらないときに設定全体を書き直すと、原因が増えます。次の順番で一段ずつ確認します。

  1. claude mcp listで、対象名とスコープが見えるか
  2. claude mcp get <名前>で、URLまたは起動コマンドが正しいか
  3. /mcpで、承認待ち、認証待ち、接続失敗のどれか
  4. 読み取りだけの最小操作が成功するか

名前がなければ追加処理、設定が違えば引数やスコープ、認証待ちならログイン、接続失敗ならサーバーの起動やURLを疑います。stdio方式では、コマンドが単独で起動できるか、実行ファイルのパスが通っているか、必要な環境変数があるかを確認します。HTTP方式では、URLの入力間違い、認証方法、ネットワーク到達性を分けて見ます。

認証エラーや接続先が見つからないエラーは、同じ条件で繰り返しても改善しません。最後に出た状態を記録し、一つだけ条件を直して再確認します。実在サービス固有のエラー文や復旧手順は提供元によって変わるため、各サービスの公式資料で※要確認です。

削除できる構成にして確認記録を残す

試用前に、追加した名前、スコープ、目的、許可した権限、削除コマンドをメモします。使わないと決めたら、公式の管理コマンドで外します。

claude mcp remove example
claude mcp list

削除後に一覧から消えたことまで確認します。OAuthで外部サービスへログインした場合は、MCP設定の削除だけで外部側の認可まで失効するかはサービスごとに異なります。Claude Codeの/mcpには認証を消去する操作がありますが、外部サービス側での連携解除も必要かは提供元の公式手順で※要確認です。

接続を増やす基準は、「今ある一つで足りない作業が具体的にあるか」です。目的が重なるサーバーを並べず、一つ追加して読み取りで確認し、必要なら権限を広げ、不要なら削除する。この順番なら、設定と責任範囲が見えないまま増えるのを防げます。

よくある質問

MCPサーバーは無料で使えますか

MCPという通信方式自体と、接続先サービスの料金は別です。無料のサーバーでも、接続先APIの利用料や有料プランが必要な場合があります。追加前に、サーバー運営者と接続先サービスの公式料金ページを確認してください。

MCPを追加するとClaude Codeが自動で使いますか

接続しただけで、すべての操作が無条件に実行されるわけではありません。利用できるツールは接続先が公開した範囲に限られ、Claude Code側の権限設定や確認も関係します。まず/mcpで公開ツールを確認し、読み取り操作から試してください。

.mcp.jsonをGitへ入れても大丈夫ですか

チーム共有する接続定義として利用できますが、APIキーやトークンの値は入れません。環境変数参照へ分離し、URL、起動コマンド、要求権限もレビュー対象にします。リポジトリから取得した.mcp.jsonは、Claude Code上で承認されるまで接続されません。

localとuserは何が違いますか

どちらも自分だけが使う設定ですが、localは現在のプロジェクトだけ、userは自分の全プロジェクトで読み込まれます。初回の試用や案件固有の接続にはlocal、複数案件で継続利用する接続にはuserが候補です。

公式情報の確認メモ

続き（結論と実データ）はnoteに置いています

ここでは手順のところまで書きました。実際に出た数字、うまくいかなかった条件、そのまま使える設定ファイルは、 note の記事にまとめてあります。

noteで続きを読む Xをフォローする

🚀 入門

Claude Code完全ガイド｜導入・指示・権限・自動化・トラブル対応の全体像

Claude Codeを初めて使う人が、導入からプロジェクトルール、権限管理、Hooks、MCP、検品、引継ぎまでを安全に組み立てるための総合ガイドです。
🚀 入門

Claude Codeが前の指示を忘れるときの対策｜コンテキスト不足を見分けて立て直す

Claude Codeが前の指示を忘れたように見える原因を、コンテキスト不足と仕様不足に分け、短い記録、工程分割、差分確認で安全に立て直す手順を解説します。
🚀 入門

Claude Codeのカスタムコマンド作成入門｜繰り返す指示を短く再利用する

Claude Codeで繰り返す指示をカスタムコマンドとして再利用する方法を、現在推奨されるSkills形式、保存場所、引数、チーム共有、トラブル対処まで解説します。