MCPとは？ Claude Codeが外部ツールとつながるための仕組み

MCP（Model Context Protocol）は、AIと外部ツールがやり取りするための共通仕様です。

Claude CodeはこのMCPに対応しており、MCPサーバーを追加することで、外部APIや各種ツールと接続できます。つまり、MCPは「接続ルール」、MCPサーバーは「そのルールに沿って機能を提供する接続先」です。

リモートMCPサーバーとローカルMCPサーバーの違い

Claude Codeで追加できるMCPサーバーには、大きく2つの種類があります。
ひとつは、公開されているURLに接続して使うリモートMCPサーバーです。もうひとつは、自分のPC上でコマンドとして起動して使うローカルMCPサーバーです。

SaaSやクラウドサービスと連携する場面では、リモートMCPサーバーを使うことが多くなります。ローカルMCPサーバーは、手元のツールやスクリプトをClaude Codeから使いたいときに登場します。

Claude Codeのインストール方法

MCPサーバーを追加する前に、Claude Code本体が必要です。
すでにインストール済みの場合は、このまま次の章に進んでください。

Claude Code公式では、現在はネイティブインストーラーが推奨されています。npmでのインストールは非推奨です。

macOS / Linux

curl -fsSL https://claude.ai/install.sh | bash

Windows

# PowerShellの場合
irm https://claude.ai/install.ps1 | iex

# CMDの場合
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windowsでは Git for Windows が必要です。
インストール後は、新しくターミナルを開いて claude を実行します。必要に応じて claude doctor を使うと、インストール状態やバージョンを確認できます。

Claude CodeでMCPサーバーを追加する方法

ここからは、Claude CodeでMCPサーバーを追加する手順を見ていきます。
MCPサーバーの追加には claude mcp add コマンドを使います。

最初に見ておくと流れをつかみやすいコマンドは、次の3つです。

# MCPサーバーを追加
claude mcp add <サーバー名> ...

# 追加済みサーバーを一覧表示
claude mcp list

# Claude Code内で接続状態を確認
/mcp

リモートMCPサーバーの追加方法

リモートMCPサーバーを追加するときは、接続先のURLを指定します。
SaaSやクラウドサービスと連携する場合は、この形で設定することが多くなります。

# 基本形
claude mcp add --transport http <サーバー名> <URL>

# 実例: Notion のリモートMCPサーバーを追加
claude mcp add --transport http notion https://mcp.notion.com/mcp

ヘッダー認証が必要な場合は、URLに加えて -H（--header）で認証情報を渡します。

# ヘッダー認証が必要な場合
claude mcp add --transport http my-api https://api.example.com/mcp -H "Authorization: Bearer YOUR_TOKEN"

OAuthに対応したMCPサーバーでは、追加後に /mcp から認証を進める形になります。

SSE（Server-Sent Events）は旧方式です。新しく追加する場合はHTTPを使うほうが整理しやすくなります。既存のSSEサーバーに接続する場合は --transport sse が使えます。

ローカルMCPサーバーの追加方法

ローカルMCPサーバーは、自分のPC上でコマンドとして起動するMCPサーバーです。
Claude Codeでは、このタイプのサーバーを追加するときに stdio トランスポートを使います。

書き方のポイントは、-- の前が Claude Code 側の設定、-- の後が実際に起動するコマンド、という形で分けて考えることです。

# 基本形
claude mcp add [オプション] <サーバー名> -- <起動コマンド>

# 実例: ローカルMCPサーバーを追加
claude mcp add --transport stdio -e API_KEY=xxx my-server -- npx -y some-mcp

このコマンドは、次のように見ると整理しやすくなります。

• --transport stdio -e API_KEY=xxx
  → Claude Code 側の設定
• my-server
  → Claude Code上で表示されるサーバー名
• --
  → ここから先はローカルMCPサーバーの起動コマンド
• npx -y some-mcp
  → 自分のPC上で実行されるコマンド

つまずきやすいのは、Claude Code 側のオプションをサーバー名の後ろに書いてしまうケースです。

# 間違い
claude mcp add my-server --transport stdio -- npx -y some-mcp

ローカルMCPサーバーでは、--transport、-e、--scope などのオプションをサーバー名の前に置く書き方になります。
unknown option エラーが出たときは、まずこの順序を確認してみてください。

なお、この順序ルールはローカルMCPサーバーを追加する stdio 構文の話です。リモートMCPサーバーをHTTPで追加する場合は書き方が異なります。

add と add-json の違い

claude mcp add は、MCPサーバーを追加する基本のコマンドです。
claude mcp add-json は、その設定をJSON形式でまとめて渡したいときに使います。

通常は add で書ける場面が多いですが、ヘッダーやOAuth設定などをまとめて整理したい場合は add-json のほうが見通しをつけやすくなります。

# 基本は add
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 設定をJSONでまとめて渡す場合は add-json
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

コマンドの形でそのまま書けるなら add、設定をひとまとまりで扱いたいときは add-json、という形で見分けると整理しやすくなります。

.mcp.json と3つのスコープの違い

MCPサーバーの設定では、「どこに保存されるか」と「誰が使えるか」を決めるためにスコープを使います。
Claude Codeでは、同じMCPサーバーでも保存するスコープによって、共有範囲と管理しやすさが変わります。

3つのスコープの違い

Claude Codeで使うスコープは、local、project、user の3つです。

選ぶときは、次のように考えると整理しやすくなります。

• 自分だけで試したいときは local
• チームで共有したいときは project
• どのプロジェクトでも自分用として使いたいときは user

同じ名前のサーバーが複数のスコープにある場合は、local → project → user の順で優先されます。

なお、MCPの local スコープは、.claude/settings.local.json とは別のものです。
MCPの local スコープは ~/.claude.json 側に保存されます。

.mcp.json は project スコープで使うファイル

.mcp.json は、project スコープのMCPサーバー設定を保存するファイルです。
プロジェクトルートに置かれ、Gitで管理しやすい形になっています。チームで同じMCPサーバー構成を共有したいときは、このファイルが中心になります。

たとえば、project スコープで追加した設定は次のような形になります。

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

この例では、URLやヘッダーに環境変数展開を使っています。
そのため、設定ファイル自体はチームで共有しつつ、APIキーのような値は各メンバーのローカル環境変数から読み込む形にできます。

project スコープのサーバーは、利用する前に Claude Code が承認を求めます。
そのため、.mcp.json がリポジトリに含まれていても、メンバーが内容を確認せずに自動実行される形にはなりません。

セキュリティ面では、.mcp.json にAPIキーやトークンを直接書かず、設定だけを共有し、認証情報は各自の環境変数で持つ形にすると扱いやすくなります。

MCPサーバーの認証方法

MCPサーバーは、追加しただけでそのまま使える場合もあれば、認証が必要な場合もあります。
Claude Codeでは、認証方法は大きく2つあります。

ひとつは OAuth によるブラウザ認証、もうひとつは APIキーやアクセストークンをヘッダーで渡す方法です。

OAuth対応サーバーの認証方法

Notion や GitHub など、OAuth に対応したMCPサーバーでは、サーバーを追加したあとに Claude Code 内で `/mcp` を開いて認証を進めます。
ブラウザでログインと認可を完了すると、その接続を Claude Code で使えるようになります。

認証が必要なサーバーかどうかは、公式ドキュメントや提供元のセットアップ手順を見ると判断しやすくなります。

ヘッダー認証が必要なサーバーの認証方法

APIキーやアクセストークンを使うMCPサーバーでは、`-H` または `--header` で認証情報を渡します。
HTTPサーバーを追加するときに、URLとあわせてヘッダーを指定する形です。Claude Code公式でも、Bearerトークンを `--header` で渡す例が案内されています。

# ヘッダー認証の例
claude mcp add --transport http my-cms https://mcp.example.com/mcp -H "X-API-TOKEN: your-token-here"

OAuthと違ってブラウザは開かないため、必要なヘッダー名や値は接続先のドキュメントで確認しておくと整理しやすくなります。

接続前に確認しておきたいこと

Claude Code公式では、サードパーティのMCPサーバーについて、Anthropicが正確性やセキュリティを検証していないこと、信頼できないコンテンツを取得するサーバーにはプロンプトインジェクションのリスクがあることが案内されています。

追加する前は、次の点を確認しておくと扱いやすくなります。

• 公式ドキュメントや提供元の説明が公開されているか
• 認証方式が OAuth なのか、ヘッダー認証なのかが明確か
• project スコープで共有する前に、まずは自分の環境で動作を確かめられるか
• APIキーやトークンを .mcp.json に直接書かず、環境変数などで分けて管理できるか

トークン消費を抑える運用テクニック

MCPサーバーを増やすほど、セッション開始時に読み込まれるツール定義も増え、コンテキスト消費が大きくなります。
対応方法としては、Tool Search を使う方法と、--mcp-config で構成を切り替える方法があります。

Tool Searchで不要なツールを動的に除外する

Tool Search機能を有効にすると、Claude Codeは必要なツールだけを動的に検索・読み込みます。MCPツール定義がコンテキストの10%を超えると自動で有効になりますが、明示的に有効化しておくのが確実です。

# 環境変数で起動時に有効化
ENABLE_TOOL_SEARCH=true claude

# 永続化する場合は settings.json の env に追加
{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

コンテキストの使用量は、セッション中に /context コマンドで確認できます。

--mcp-config で用途別プロファイルを切り替える

作業内容に応じてMCPサーバー構成を切り替える方法もあります。用途別の設定ファイルを用意し、起動時に読み込むファイルを指定します。

# 軽量な構成で起動（ドキュメント参照のみ）
claude --mcp-config ~/.claude/light.mcp.json

# 開発フル構成で起動（全サーバー接続）
claude --mcp-config ~/.claude/dev.mcp.json

たとえば、日常の調査にはContext7（最新ライブラリドキュメントを参照するMCPサーバー）だけの軽量構成、開発タスクにはPlaywright（ブラウザ自動操作のMCPサーバー）＋GitHub＋Context7のフル構成、というように使い分けると効率的です。

light.mcp.json の例:

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

dev.mcp.json の例:

{
  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

--strict-mcp-config を併用すると、指定ファイルのみを使用し、他の設定を無視します。

# 指定した設定のみを使用（他のスコープの設定を無視）
claude --mcp-config ~/.claude/light.mcp.json --strict-mcp-config

日常的に使うサーバーは3〜5個程度に絞るのが実用的です。

トラブルシューティング

MCPの設定で遭遇しやすいエラーと、その対処法をまとめます。

オプション順序のエラー

「unknown option」が表示される場合、--transport や -e をサーバー名の後に書いていないか確認してください。stdioの構文では、すべてのオプションをサーバー名の前に移動する必要があります。

# エラーになる（stdioの場合）
claude mcp add my-server --transport stdio -- npx -y some-mcp

# 正しい
claude mcp add --transport stdio my-server -- npx -y some-mcp

接続・起動のエラー

Windows固有の問題

Windows環境では、stdioサーバーに cmd /c ラッパーが必要な場合があります。

# cmd /c ラッパーを使う
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

cmd /c がないと「Connection closed」エラーが発生します。また、Claude CodeのWindows版はGit for Windowsが必要です。未インストールの場合はインストールしてください。

設定の競合

意図しないサーバーが接続される場合、claude mcp list で確認し、不要なサーバーを claude mcp remove <名前> で削除してください。local > project > user の優先順位で設定が読み込まれるため、同名サーバーが複数スコープに存在すると混乱の原因になります。

チーム開発でMCPを運用するベストプラクティス

基本は .mcp.json をGit管理し、認証情報は環境変数で分離します。エンタープライズでは managed-mcp.json による排他制御も選択できます。

.mcp.json をGit管理し、認証情報は分離する

チームで共有するMCPサーバー設定は --scope project で追加し、.mcp.json をGitリポジトリに含めます。

# プロジェクトのディレクトリ構成
.mcp.json                      # ← Git管理する（チーム共通）
.claude/settings.local.json    # ← .gitignore に追加（個人の認証情報）

エンタープライズ向け：managed-mcp.json による排他的統制

組織全体でMCPサーバーを統制したい場合は、managed-mcp.json を使います。管理者がシステムディレクトリにこのファイルをデプロイすると、定義されたサーバー以外は追加・変更・使用できなくなる排他制御になります。

完全な排他制御ではなく、ユーザーに一定の自由度を持たせたい場合は、managed-settings.json のallowlist / denylistによるポリシーベースの制御も選択できます。

まとめ

覚えるべきは、claude mcp add の構文、.mcp.json によるチーム共有、スコープの使い分けの3つです。トークン消費が気になったら、Tool Searchと --mcp-config によるプロファイル切り替えで対処できます。

まずはリモートMCPサーバーを1つ追加し、/mcp で接続状態を確認してみてください。
そのあと、チームで共有したい設定が出てきたら .mcp.json と project スコープを使う、という順で広げていくと整理しやすくなります。