Claude Code MCP設定ガイド — claude mcp addの構文からスコープ・認証まで

MCP(Model Context Protocol)は、AIアプリケーションと外部ツール / データソースをつなぐオープン標準のプロトコルです。Claude CodeはMCPクライアントとして動作し、claude mcp add の1コマンドでGitHub / Sentry / Notion / PostgreSQLといった数百の外部サービスに接続できます。

接続したサーバーの設定は .mcp.json(プロジェクト共有)または ~/.claude.json(個人用)に保存され、スコープ・認証・出力制限をすべてCLIから制御できます。追加コマンドの正確な構文、3つの設定スコープの使い分け、OAuth認証、トラブルシュートまでを順に確認します。MCPサーバーを自作したい場合はMCPサーバーをTypeScriptで自作する手順、Google DriveやSlackなど個別サービスの接続例はMCP実用ガイドが対応します。

Claude Code MCPとは

Claude CodeのMCP対応とは、外部システムを「ツール」としてClaudeに渡すための標準接続層です。MCPサーバーを接続すると、Claude Codeは課題追跡ツールの読み取り、データベースへのクエリー実行、SlackやFigmaの参照といった操作を、コピー&ペーストなしで直接実行できるようになります。

接続後にできることの代表例は次の通りです。

• 課題追跡ツールのチケット内容を読んで機能を実装し、GitHubにPRを作成する
• SentryやStatsigの監視データを分析して、エラーの原因を特定する
• PostgreSQLデータベースに自然言語でクエリーを投げ、結果を集計する
• Slackに投稿されたFigmaデザインを基にテンプレートを更新する
• MCPサーバーをチャネル(外部イベントの受信口)として使い、webhookやチャットに反応する

データベースに接続する場合は、書き込みまで許可するかどうかで事故時の影響範囲が変わります。読み取り専用ユーザーとpermissionsルールで書き込みを止める設計はClaude CodeでMCPからデータベースに接続する方法にまとめています。

デザインファイルを直接読ませたい場合は、Figma MCPサーバーの使い方で接続手順とコード生成の流れを扱っています。

仕組みとしては、MCPサーバーが外部システムをプロトコル準拠の形で公開し、Claude Codeがクライアントとしてそれを呼び出します。サーバーが公開できる能力はTools(関数呼び出し)/ Resources(参照可能なデータ)/ Prompts(プロンプトテンプレート)の3種類で、それぞれ呼び出し方が異なります(後述)。

MCPサーバーを追加する(claude mcp add)

サーバーの追加は claude mcp add で行います。リモートサーバーは --transport http でURLを指定し、ローカルで動かすサーバーは -- 区切りで起動コマンドを渡す、というのが基本形です。

リモートHTTPサーバーの追加例:

# 基本構文
claude mcp add --transport http <name> <url>
 
# Notionに接続する例
claude mcp add --transport http notion https://mcp.notion.com/mcp
 
# Bearerトークン付きで認証ヘッダーを渡す例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

ローカルstdioサーバーの追加例:

# 基本構文
claude mcp add [options] <name> -- <command> [args...]
 
# Airtableサーバーを環境変数付きで追加する例
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

JSON設定が手元にある場合は claude mcp add-json で直接登録できます。

# JSON文字列からHTTPサーバーを追加
claude mcp add-json weather-api \
  '{"type":"http","url":"https://api.weather.com/mcp"}'
 
# stdioサーバーをJSONで追加
claude mcp add-json local-weather \
  '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"]}'

追加後の管理コマンドは次の4つを押さえれば足ります。

トランスポート4方式の使い分け

接続方式(トランスポート)は4種類ありますが、迷ったらリモートはHTTP、ローカルはstdioの2択です。SSE(Server-Sent Events)は非推奨になっており、新規の接続には使わない扱いになっています。

stdioサーバーには、Claude Codeがプロジェクトルートを示す環境変数 CLAUDE_PROJECT_DIR を自動で渡します。サーバー実装側はこの値を読めば、作業ディレクトリに依存せずプロジェクト相対パスを解決できます。

接続の安定性にも方式ごとの差があります。HTTP / SSEサーバーがセッション中に切断された場合、Claude Codeは1秒から始まる指数バックオフで最大5回まで自動再接続します。さらにv2.1.121以降は、起動時の初期接続も5xx応答やタイムアウトなどの一時エラーなら最大3回再試行します。stdioサーバーはローカルプロセスのため自動再接続の対象外です。

設定スコープの使い分け(local / project / user)

--scope フラグは「そのサーバーがどのプロジェクトで読み込まれ、誰と共有されるか」を決めます。既定はlocalで、チームと共有したいときだけprojectを選ぶ、が基本線です。

# チーム共有するprojectスコープで追加(.mcp.jsonに書き込まれる)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp
 
# 全プロジェクトで使うuserスコープで追加
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

使い分けの判断は次の早見表が目安になります。

同じ名前のサーバーが複数スコープに定義されている場合、優先順位はlocal → project → user → プラグイン提供 → Claude.aiコネクタの順です。優先されたスコープの定義が丸ごと使われ、フィールド単位でのマージは行われません。「projectの設定をベースにlocalでトークンだけ上書き」のような部分上書きはできない点に注意が必要です。

セキュリティ上の理由から、.mcp.json 由来のprojectスコープサーバーは初回利用前に承認を求められます。承認の選択をやり直したいときは claude mcp reset-project-choices でリセットできます。なお、サーバー名 workspace は内部用に予約されており、設定しても読み込み時にスキップされます。

.mcp.jsonの書き方と環境変数展開

.mcp.json はプロジェクトルートに置く共有設定ファイルで、mcpServers キーの下にサーバー定義を並べます。APIキーのような秘密情報は直接書かず、環境変数の展開構文で参照するのが定石です。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/tools/mcp-server.js"],
      "env": {
        "CACHE_DIR": "/tmp"
      },
      "timeout": 600000
    }
  }
}

展開構文は2種類で、${VAR} は環境変数 VAR の値に、${VAR:-default} は未設定時にデフォルト値へ展開されます。展開できるフィールドは command / args / env / url / headers の5つです。必要な環境変数が未設定でデフォルト値もない場合、Claude Codeは設定の解析自体に失敗するため、チーム共有する .mcp.json ではデフォルト値付きの構文が安全寄りの書き方になります。

サーバー定義には接続設定以外のフィールドも置けます。

• timeout: そのサーバーのツール実行タイムアウト(ミリ秒)。例の 600000 は10分
• alwaysLoad: true でツール検索の遅延読み込み対象から除外(v2.1.121以降、後述)
• oauth: 事前設定のOAuth認証情報やスコープ制限(次節)

なお、MCPサーバーの設定は settings.json には書きません。permissionsやHooksを管理する settings.json 系列とは別ファイルで、保存先は前節の表の通り ~/.claude.json と .mcp.json の2系統です。設定ファイル全体の構造はClaude Code設定ファイル完全ガイドで整理しています。

リモートサーバーの認証(OAuthと/mcpコマンド)

認証が必要なリモートサーバーは、追加してからセッション内で /mcp を実行し、ブラウザーでログインする2段階で接続します。Claude CodeはOAuth 2.0をサポートしており、サーバーが401または403を返すと「認証が必要」とマークして /mcp パネルに表示します。

# 1. 認証が必要なサーバーを追加(例: Sentry)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

/mcp からブラウザーが開き、ログインを完了すると接続されます。取得したトークンは安全に保存され、自動更新されるため、毎回のログインは不要です。アクセスを取り消したいときは /mcp メニューの「Clear authentication」を使います。

一部のサーバーは動的クライアント登録(Dynamic Client Registration)に対応しておらず、「Incompatible auth server: does not support dynamic client registration」というエラーになります。この場合はサーバー側の開発者ポータルでOAuthアプリを登録し、クライアントIDとコールバックポートを指定して追加します。

# 事前登録したOAuthクレデンシャルで追加
# (--client-secretはマスク付き入力でシークレットを尋ねる)
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

クライアントシークレットはmacOSならシステムキーチェーンに保存され、設定ファイルには残りません。CIなど対話入力ができない環境では環境変数 MCP_CLIENT_SECRET で渡せます。

OAuth以外の社内認証(Kerberosや短期トークンなど)を使うサーバーには、.mcp.json の headersHelper フィールドで「接続時にヘッダーを生成するコマンド」を指定する方法があります。コマンドは10秒のタイムアウト内に、文字列キーと値のJSONオブジェクトを標準出力へ書き出す必要があり、生成されたヘッダーは同名の静的 headers を上書きします。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

出力制限とタイムアウトの調整

MCP連携で実運用に効くのが、タイムアウトと出力トークンの上限管理です。既定値を知らないと「ツールが途中で打ち切られる」「大きな結果が警告される」原因が特定できません。

サーバー個別の timeout(ミリ秒)はツール呼び出しごとのハードリミットで、サーバーからの進捗通知があっても延長されません。1000未満の値は1秒として扱われ、HTTP / SSEではリクエストの最初の応答までに最低60秒の猶予が確保されます。

大きな出力を返すサーバー(データベーススキーマの取得、大規模ログの解析など)では、上限を引き上げてから起動します。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

サーバー実装者側の手段として、ツール定義の _meta に anthropic/maxResultSizeChars を宣言すると、そのツールだけ最大500,000文字まで上限を引き上げられます。宣言がない場合、しきい値を超えた結果はディスクに保存され、会話内にはファイル参照として渡されます。

接続サーバーが増えてきたときに効くのがツール検索(Tool Search)です。既定で有効になっており、セッション開始時にはツール名とサーバー説明だけを読み込み、ツール定義本体はClaudeが必要としたときに遅延読み込みします。MCPサーバーを増やしてもコンテキストウィンドウの消費がほぼ増えない仕組みで、ENABLE_TOOL_SEARCH 環境変数で挙動を変えられます。

• auto: ツール群がコンテキストの10%に収まるなら事前読み込み、超えたら遅延
• auto:5 のように数値指定でしきい値を変更
• false: すべて事前読み込み(従来挙動)
• 特定サーバーだけ常時読み込みたい場合は、そのサーバー定義に alwaysLoad: true

ツール検索はSonnet 4以降またはOpus 4以降のモデルが前提で、Haiku系では動作しません。

リソース参照とMCPプロンプト

MCPサーバーが公開するのはツールだけではありません。Resourcesは @ メンションで、Promptsはスラッシュコマンドで、それぞれ会話から直接呼び出せます。

リソースは @server:protocol://resource/path の形式で参照します。プロンプト入力中に @ を打つと、接続中のサーバーが公開するリソースがファイルと並んでオートコンプリートに出ます。

@github:issue://123 を分析して修正を提案できますか?
@postgres:schema://users と @docs:file://database/user-model を比較してください

参照されたリソースは自動で取得され、添付ファイルとして会話に含まれます。1つのプロンプトで複数リソースを参照しても構いません。

サーバーが公開するプロンプトは /mcp__サーバー名__プロンプト名 の形式のコマンドになります。引数はスペース区切りで渡せます。

/mcp__github__list_prs
/mcp__jira__create_issue "ログインフローのバグ" high

また、MCPサーバーは作業の途中でユーザーへの構造化された質問(応答要求)を出せます。フォーム入力型とブラウザーURL型の2方式があり、Claude Codeが自動でダイアログを表示するため設定は不要です。応答要求への自動応答を組みたい場合はElicitation hookが対応します。Hooksの仕組みはClaude Code Hooks完全ガイドで扱っています。

Claude DesktopやClaude.aiとの連携

Claude Desktopで設定済みのMCPサーバーは、claude mcp add-from-claude-desktop で対話的に選んでインポートできます。対応プラットフォームはmacOSとWSL(Windows Subsystem for Linux)で、同名サーバーが既にある場合は server_1 のような数値サフィックスが付きます。Desktop側のMCP導入方法はDesktop Extensions(.dxt)でMCPサーバーを追加する方法が詳しいです。

逆方向の連携として、Claude Code自体をMCPサーバーにする claude mcp serve もあります。Claude Desktopの claude_desktop_config.json に登録すれば、DesktopからClaude CodeのView / Edit / LSといったツールを呼び出せます。

# Claude Codeをstdio MCPサーバーとして起動
claude mcp serve

Claude.aiアカウントでClaude Codeにログインしている場合、claude.ai側で追加したコネクタは自動的にClaude Codeでも使えます。TeamおよびEnterpriseプランではコネクタの追加は管理者のみが行えます。挙動を切りたいときは ENABLE_CLAUDEAI_MCP_SERVERS=false で無効化できます。なお、コネクタが読み込まれるのはアクティブな認証方法がClaude.aiサブスクリプションのときだけで、ANTHROPIC_API_KEY やBedrock / Vertex経由の認証では読み込まれません。

VS Code本体が持つMCP機能(GitHub Copilot Chat向けのmcp.json)は、ここまで扱ってきたClaude CodeのMCP設定とは別物です。設定ファイルの場所も対応するチャットクライアントも独立しているため、混同しないよう注意が必要です。設定手順はVS Code MCP設定ガイドにまとめています。

ネイティブツールとMCPの使い分け

Claude Codeに元から備わるBash / Edit / Readなどのネイティブツールと、MCPサーバーが提供するツールは役割が重なることがあります。判断軸は「外部サービスか」「複数クライアントで使い回すか」の2点です。

ローカルのファイル操作やgit操作はネイティブツールで完結します。外部サービス(GitHub API / Slack / DB)との統合、OAuthが必要な接続、チームや複数クライアントで共有したい統合がMCPの守備範囲です。Claude Code全体の機能体系から位置付けを掴みたい場合はClaude Code完全ガイドが起点になります。

よくあるつまずきと対処

実際の導入で報告の多い失敗パターンを、原因と対処のセットでまとめます。

オプションをサーバー名の後ろに書いて解釈されない

claude mcp add myserver --env KEY=value -- npx server のような順序は誤りです。すべてのオプションはサーバー名の前、-- 以降はサーバー側コマンドという規則を守ると解決します。

projectスコープのサーバーが「Pending approval」のまま動かない

.mcp.json 由来のサーバーは初回に承認が必要で、未承認のものは claude mcp list に「⏸ Pending approval」と表示されます。claude を対話モードで起動して承認するか、選択をやり直す場合は claude mcp reset-project-choices を実行します。

OAuthで「dynamic client registrationに非対応」エラーが出る

サーバーが自動クライアント登録に対応していないケースです。開発者ポータルでOAuthアプリを登録し、--client-id と --client-secret、登録済みリダイレクトURIと一致する --callback-port を付けて追加し直します。

認証ヘッダーを設定したのにOAuthに進めない

headers.Authorization を設定済みのサーバーがそのヘッダーを拒否した場合、Claude CodeはOAuthへフォールバックせず接続失敗として報告します。トークンがMCPエンドポイントで有効かを確認するか、OAuthフローを使うならヘッダー設定を削除します。

.mcp.jsonの解析に失敗する

${VAR} で参照した環境変数が未設定で、デフォルト値もない場合に起きます。${VAR:-default} 形式に変えるか、必要な変数をチームのセットアップ手順に明記して回避します。

ツール出力が大きすぎると警告される

出力が10,000トークンを超えると警告が出ます。MAX_MCP_OUTPUT_TOKENS(既定25,000)を引き上げるか、サーバー側で応答のページネーションや anthropic/maxResultSizeChars 注釈の追加を検討します。

stdioサーバーが起動しない

command / args のパス誤りが大半です。設定したコマンドをそのままターミナルで手動実行してエラーメッセージを確認するのが最短です。起動が遅いサーバーは MCP_TIMEOUT の引き上げで解決することもあります。

接続したいサーバー名が使えない

workspace という名前は内部用に予約されています。設定しても読み込み時にスキップされるため、別名に変更します。

よくある質問

Claude CodeにMCPサーバーを追加するコマンドは?

claude mcp add です。リモートサーバーは claude mcp add --transport http <name> <url>、ローカルサーバーは claude mcp add <name> -- <command> の形で追加し、claude mcp list で接続状態を確認できます。

MCPの設定はどのファイルに保存されますか?

localスコープとuserスコープは ~/.claude.json、projectスコープはプロジェクトルートの .mcp.json に保存されます。Hooksやpermissionsを置く settings.json とは別ファイルです。

SSEトランスポートはまだ使えますか?

接続自体は可能ですが非推奨の位置付けです。サーバーがHTTP(streamable HTTP)に対応している場合はHTTPでの接続が推奨されています。

Claude.aiで追加したコネクタはClaude Codeでも使えますか?

使えます。Claude.aiアカウントでログインしていれば自動的に /mcp の一覧に表示されます。ただしAPIキーやBedrock / Vertex認証で動かしている場合は読み込まれません。

MCPサーバーを増やすとコンテキストを圧迫しませんか?

既定で有効なツール検索が、ツール定義を必要時にだけ読み込む方式のため、サーバーを増やしてもセッション開始時のコンテキスト消費はほぼ増えません。常時読み込みたいサーバーだけ alwaysLoad: true を付ける運用ができます。

MCPツールの呼び出しが途中で切れるときは?

サーバー定義の timeout フィールド(ミリ秒)でそのサーバーのツール実行上限を延ばせます。起動段階で失敗する場合は MCP_TIMEOUT、出力サイズの問題なら MAX_MCP_OUTPUT_TOKENS がそれぞれ対応します。

まとめ

Claude CodeのMCP設定は、claude mcp add での追加 → スコープの選択 → 必要なら /mcp で認証、という3手順に集約されます。運用での判断軸は次の3つです。

1. リモートはHTTP、ローカルはstdioを選ぶ(SSEは非推奨、WebSocketはイベントプッシュ用途のみ)
2. 個人利用はlocal / user、チーム共有は .mcp.json のprojectスコープに置き、秘密情報は環境変数展開で逃がす
3. タイムアウト(MCP_TIMEOUT / timeout)と出力上限(MAX_MCP_OUTPUT_TOKENS)の既定値を把握しておく

ネイティブツールで済む処理にMCPを足す必要はなく、外部サービス連携・認証付き接続・複数クライアント共有が出てきた時点で導入すれば十分です。サーバーの自作に進む場合はMCPサーバーをTypeScriptで自作する手順、接続先サービス別の実例はMCP実用ガイドが次のステップになります。