.mcp.json設定リファレンス：Claude Code MCPセットアップ完全ガイド（2026年版）

Claude CodeのMCPセットアップには「わかりにくい」という評判があります。サーバーを追加したのに表示されない。READMEから設定をコピーしたのにサイレントに失敗する。.mcp.jsonと~/.claude.jsonのどちらに書くべきかわからない。そしてStack Overflowでclaude_desktop_config.jsonへの言及を何十件も見つけるが、それはまったく別のファイルです。

この記事はMCP設定スキーマのすべてのフィールド、スコープ階層の実際の動作、そして15の人気MCPサーバーのテスト済み設定を網羅した完全リファレンスです。曖昧な説明はしません。すべてのフィールドに意味があります。

2つの設定ファイル：.mcp.json vs claude_desktop_config.json

まず最も一般的な混乱の原因を明確にします。

**.mcp.json**はClaude Codeのプロジェクトスコープの設定ファイルです。プロジェクトのルートディレクトリに置き、バージョン管理にチェックインし、チームメンバー全員のための共有MCPサーバーをロードします。ほとんどの開発ワークフローで使うべきファイルです。

**claude_desktop_config.json**はスタンドアロンGUIアプリケーションであるClaude Desktop用の設定ファイルです。macOSでは~/Library/Application Support/Claude/claude_desktop_config.jsonに、Windowsでは%APPDATA%\Claude\claude_desktop_config.jsonに置かれます。Claude CodeはこのファイルをCLIから直接読み取りません。Claude Desktopのドキュメントから設定をコピーしてもClaude CodeのCLIで動作しない理由がここにあります。

なお、JSONの構造はほぼ同一です。claude_desktop_config.jsonで動作するサーバーエントリは、最小限の変更またはそのまま.mcp.jsonでも動作します。スキーマは同じで、ファイルの場所とロードメカニズムが異なります。

クイックインポート: Claude Desktopですでにサーバーを設定している場合は次のコマンドでClaude Codeにインポートできます。

claude mcp add-from-claude-desktop

macOSとWSLで動作します。標準の場所からClaude Desktopの設定を読み取り、インポートするサーバーを選択できます。

ファイルの場所とスコープ階層

Claude CodeのMCPサーバーには3つのスコープがあり、それぞれ異なる場所に保存されます。

プロジェクトスコープは.mcp.jsonの主なユースケースです。ファイルをコミットすると、リポジトリをクローンした全員が同じサーバーを使えます。Claude Codeは.mcp.jsonからプロジェクトスコープのサーバーを初めてロードする前にセキュリティプロンプトを表示します。他の誰かのコードベースからのファイルにコマンドが含まれている可能性があるためです。

ローカルスコープは--scopeフラグなしでclaude mcp addを実行した場合のデフォルトです。現在のプロジェクトパス配下のエントリとして~/.claude.jsonにサーバーを保存します。他の誰にも見えません。

ユーザースコープ（--scope user）はすべてのプロジェクトでロードされるよう~/.claude.jsonのグローバルエントリにサーバーを保存します。

同じサーバー名が複数のスコープに現れる場合、優先順位は次のとおりです: Local > Project > User > プラグイン提供 > Claude.aiコネクター。最も高いスコープの定義がすべてを勝ちます——フィールドはスコープをまたいでマージされません。

組織向けの第4のレベルもあります: managed-mcp.jsonで、管理者がシステムパス（macOSでは/Library/Application Support/ClaudeCode/managed-mcp.json、Linuxでは/etc/claude-code/managed-mcp.json）に展開します。このファイルが存在すると排他的な制御権を持ち、ユーザーはMCPサーバーを追加・変更できません。

完全スキーマリファレンス

すべての.mcp.jsonファイルはこのトップレベル構造に従います。

{
  "mcpServers": {
    "<server-name>": { ... }
  }
}

mcpServersオブジェクトはサーバー名からサーバー設定へのマップです。サーバー名は自分で選ぶ文字列で、claude mcp listの識別子、ツール名のプレフィックス（/mcp__servername__toolname）、/mcpのラベルになります。

予約名: workspaceという名前はClaude Codeが内部使用のために予約しています。設定でその名前のサーバーを定義すると、Claude Codeは起動時にスキップして警告をログに記録します。

共通フィールド（全トランスポートタイプ）

これらのフィールドはトランスポートに関係なく適用されます。

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "timeout": 300000,
      "alwaysLoad": false
    }
  }
}

alwaysLoadについて: Claude Codeのデフォルト動作（ツールサーチ）はMCPツール定義を遅延させ、必要に応じて検索します。多くのサーバーがある場合にコンテキスト使用を低く保ちます。alwaysLoad: trueを設定するとそのサーバーのすべてのツールがセッション開始時にコンテキストに入ります——ほぼ毎回のタスクでそのツールを使うサーバーに有用です。控えめに使用してください。

stdioサーバーフィールド

{
  "mcpServers": {
    "my-stdio-server": {
      "type": "stdio",
      "command": "/usr/local/bin/my-server",
      "args": ["--config", "/etc/my-server/config.json"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

CLAUDE_PROJECT_DIR: Claude Codeはスポーンされたすべてのstdioサーバープロセスの環境にこの環境変数を自動的に設定します。Claude Codeが起動したディレクトリ（プロジェクトルート）を指します。サーバーはprocess.env.CLAUDE_PROJECT_DIR（Node）またはos.environ["CLAUDE_PROJECT_DIR"]（Python）として読み取り、作業ディレクトリに依存せずプロジェクト相対パスを解決できます。

.mcp.json設定自体（commandまたはargs内）で${CLAUDE_PROJECT_DIR}を参照する場合は、シェル環境に変数がないときのパースエラーを避けるためにデフォルト形式${CLAUDE_PROJECT_DIR:-.}を使用してください。

HTTPサーバーフィールド

{
  "mcpServers": {
    "my-http-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Workspace-ID": "ws-123"
      },
      "headersHelper": "/path/to/auth-script.sh",
      "timeout": 600000,
      "alwaysLoad": false,
      "oauth": {
        "clientId": "your-client-id",
        "callbackPort": 8080,
        "scopes": "read write",
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

typeのエイリアシング: MCPスペックは現在のHTTPトランスポートをstreamable-httpと呼んでいます。Claude Codeはtypeフィールドの値としてhttpとstreamable-httpの両方を同等として受け付けます。streamable-httpを使用するサーバードキュメントからコピーした設定は変更なしで動作します。

OAuthオブジェクトのフィールド:

SSEサーバーフィールド

SSEトランスポートはMCP 2025-06仕様で非推奨になりました。利用可能なところではHTTPサーバーを使用してください。

{
  "mcpServers": {
    "legacy-sse-server": {
      "type": "sse",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

フィールドセットはHTTPサーバーと同一です。SSEサーバーは指数バックオフによる自動再接続をサポートします（最大5回の試行、1秒から始まり毎回2倍）。

WebSocketサーバーフィールド

{
  "mcpServers": {
    "events-server": {
      "type": "ws",
      "url": "wss://mcp.example.com/socket",
      "headers": {
        "Authorization": "Bearer ${WS_TOKEN}"
      }
    }
  }
}

WebSocketはClaudeにポーリングなしでイベントをプッシュするサーバー——CIの結果、監視アラート、Webhookイベントなど——に適しています。サーバーがリクエストに応答するだけならHTTPを使用してください。WebSocketはclaude mcp add --transportCLIフラグをサポートしません。claude mcp add-jsonを使うか.mcp.jsonを直接編集してください。

トランスポートタイプ設定

stdio: ローカルプロセス

stdioは元々のMCPトランスポートです。Claude Codeはサーバーを子プロセスとして起動し、stdinにJSON-RPCメッセージを書き込み、stdoutから応答を読み取ります。サーバーのログはstderr（Claude Codeによってキャプチャ）に出力されます。

stdioを使う場面:

• 直接ファイルシステムアクセスが必要なサーバー
• ローカルツールのラッパー（データベース、コンパイラ、カスタムスクリプト）
• ネットワーク経由で送りたくないクレデンシャルを持つサーバー
• 独自MCPサーバーの開発・テスト

主な制限: stdioサーバーはそのマシンに限定されます。チームメンバー間で実行中のstdioサーバーインスタンスを共有できません。各開発者が自分のインスタンスを実行します。

# CLI相当コマンド
claude mcp add --transport stdio --scope project \
  --env AIRTABLE_API_KEY=${AIRTABLE_API_KEY} \
  airtable -- npx -y airtable-mcp-server

HTTP（Streamable HTTP）: リモートサービス

HTTPはすべてのリモートMCPサーバーに推奨される現在のトランスポートです。サーバーは独立して動作し、複数のクライアント接続を処理します。通信はHTTP POSTリクエストを使用し、サーバーはSSEを使ってオプションでレスポンスをストリームできます。

HTTPを使う場面:

• SaaSインテグレーション（GitHub、Sentry、Notion、Slack）
• チームが運用する共有インフラサーバー
• 複数のマシンからアクセスする必要があるサーバー

# CLI相当コマンド
claude mcp add --transport http notion https://mcp.notion.com/mcp

SSE: Server-Sent Events（非推奨）

MCPプロトコル2024-11-05からのHTTP+SSEトランスポートは非推奨です。後方互換性のために一部のサーバーで引き続き実行されています。

サーバーがSSEエンドポイントのみを公開しておりStreamable HTTPにまだ移行していない場合は設定でtype: "sse"を使用してください。

# CLI相当コマンド
claude mcp add --transport sse asana https://mcp.asana.com/sse

Streamable HTTP: 2025年標準

streamable-http（Claude Codeでは単にhttp）はMCPプロトコル2025-03-26で導入され2025-06-18に改良されたトランスポートです。POSTリクエストとGET起動のSSEストリームの両方をサポートする単一エンドポイントを使用します。

SSEと比較した主な改良点:

• 2つではなく単一エンドポイント
• Mcp-Session-Idヘッダーによるセッション管理
• イベントIDによるレジューム可能なストリーム
• バージョンネゴシエーション用のMCP-Protocol-Versionヘッダー

.mcp.jsonの観点ではhttpとstreamable-httpは同一です——type値にどちらの文字列も使用できます。

認証パターン

静的APIキー（ヘッダー）

SaaSインテグレーションで最も一般的なパターン:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

${GITHUB_PAT}はロード時にシェル環境から展開されます。変数が未設定でデフォルトもない場合、Claude Codeは設定のパースに失敗します。

OAuth 2.0（リモートサーバー）

OAuthをサポートするサーバーでは、Claude Codeが自動的にフローを処理します。サーバーが401または403で応答すると、Claude Codeはそれを認証が必要としてマークし、/mcpでフローを完了します。

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

事前設定済みクレデンシャルが必要なサーバー:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "your-client-id",
        "callbackPort": 8080
      }
    }
  }
}

クライアントシークレットは設定ファイルに保存されません——システムキーチェーン（macOS）またはクレデンシャルファイルに保管されます。CLIでサーバーを追加する際に--client-secretで一度だけ渡します。

動的ヘッダー（headersHelper）

サーバーが短命のトークン、Kerberos、内部SSOシステムを使用する場合、静的ヘッダーは機能しません。headersHelperを使って接続時にヘッダーを生成するコマンドを実行します。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-token.sh"
    }
  }
}

スクリプトは10秒以内に文字列キーと値のペアのJSONオブジェクトをstdoutに出力する必要があります。Claude Codeはスクリプトの環境にCLAUDE_CODE_MCP_SERVER_NAMEとCLAUDE_CODE_MCP_SERVER_URLを設定するため、1つのスクリプトで複数のサーバーに対応できます。

#!/bin/bash
# get-mcp-token.sh
TOKEN=$(vault kv get -field=token secret/mcp/${CLAUDE_CODE_MCP_SERVER_NAME})
echo "{\"Authorization\": \"Bearer ${TOKEN}\"}"

stdioサーバー用の環境変数

stdioサーバーはマージされた環境を受け取ります: プロセス環境にenvで指定したものが加わります。機密性の高い値はシェル変数展開を使ってenvマップに入れます。

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

.mcp.jsonがバージョン管理にコミットされる場合、envマップの値にクレデンシャルをハードコードしないでください。シェル変数展開を使い、設定する必要のある変数をドキュメントに記載してください。

15種の実世界MCPサーバー設定

1. GitHub

リモートHTTPを使った公式GitHubのMCPサーバー。ClaudeにアクセスさせたいリポジトリへのパーミッションをPersonal Access Tokenで設定します。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

github.com/settings/personal-access-tokensで必要なリポジトリに限定したリポジトリアクセスを持つ細かい権限のPATを生成してください。

2. Filesystem

ファイルの読み書き用のローカルサーバー。公式@modelcontextprotocol/server-filesystemパッケージが引数として渡したディレクトリを公開します。

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents",
        "/Users/you/Projects"
      ]
    }
  }
}

パッケージ名以降の各引数が公開するディレクトリです。サーバーはこれらのディレクトリ外のパスにアクセスしません。

3. PostgreSQL

@bytebase/dbhubを使ったデータベースアクセス。読み取りとスキーマ検査をサポート。本番では読み取り専用のデータベースユーザーを使ってください。

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--dsn",
        "${DATABASE_URL}"
      ]
    }
  }
}

環境変数にDATABASE_URL=postgresql://readonly:password@host:5432/dbnameを設定してください。共有設定では、DSNをargsにハードコードせず環境変数に保管してください。

4. SQLite

軽量なローカルデータベースアクセス。ローカル開発データベースとログ分析に有用です。

{
  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "--db-path",
        "${CLAUDE_PROJECT_DIR:-/tmp}/data.sqlite"
      ]
    }
  }
}

${CLAUDE_PROJECT_DIR:-/tmp}パターンは利用可能であればプロジェクトディレクトリを使い、そうでなければ/tmpにフォールバックします。

5. Slack

公式MCPを使ったSlackインテグレーション。適切なスコープのSlackアプリが必要です。

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

追加後に/mcpで認証します。scopesフィールドはOAuthリクエストを必要な最小パーミッションに固定します——ClaudeのSlackワークスペースへのアクセスを制限したい場合に有用です。

6. Sentry

エラー監視インテグレーション。OAuthベースのためトークン管理は不要です。

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

/mcpを実行してSentryアカウントで認証します。接続後、Claudeはエラーの詳細、スタックトレース、デプロイ履歴を直接取得できます。

7. Linear

エンジニアリングチームのissueトラッキング。/mcpのOAuthフローで認証します。

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

8. Notion

ワークスペースのナレッジベース。OAuthベースのため、Notionインテグレーションのセットアップが必要です。

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

/mcpで認証します。アクセスを許可するNotionワークスペースの選択を求められます。

9. Google Drive

ドキュメントとスプレッドシートへのアクセス。GoogleのMCPサーバー経由のOAuthベースです。

{
  "mcpServers": {
    "google-drive": {
      "type": "http",
      "url": "https://drive.googleapis.com/mcp",
      "oauth": {
        "scopes": "https://www.googleapis.com/auth/drive.readonly"
      }
    }
  }
}

誤った書き込みを防ぐためにdrive.readonlyスコープを使用してください。ワークフローでファイルの作成・変更が必要な場合のみdriveスコープにアップグレードしてください。

10. ブラウザ / Playwright

テストとWeb操作のためのブラウザ自動化。デフォルトではヘッドレスで動作します。

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

ヘッドモード（表示されるブラウザウィンドウ）の場合:

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

11. Memory

セッションをまたいで持続するメモリ。Claudeが会話を通じて学習した重要な事実をローカルファイルに保存します。

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "${HOME}/.claude-memory.json"
      }
    }
  }
}

12. Time

Claudeに正確な現在時刻とタイムゾーン変換を提供します。日付に依存する機能を構築する際に意外なほど有用です。

{
  "mcpServers": {
    "time": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-time"],
      "alwaysLoad": true
    }
  }
}

ここでのalwaysLoad: trueは合理的です——時刻の検索は即座に必要で、ツールのフットプリントは最小限です。

13. EverArt

ClaudeセッションでのAI画像生成。

{
  "mcpServers": {
    "everart": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everart"],
      "env": {
        "EVERART_API_KEY": "${EVERART_API_KEY}"
      }
    }
  }
}

14. Brave Search

Brave APIを使ったWeb検索。ブラウザ自動化なしでClaudeに最新情報へのアクセスを与えるのに有用です。

{
  "mcpServers": {
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}

brave.com/search/apiでAPIキーを取得してください。無料プランには月2,000クエリが含まれます。

15. Puppeteer

ブラウザ自動化のPlaywright代替。特定のレガシーWebアプリとの互換性が優れています。

{
  "mcpServers": {
    "puppeteer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

環境変数パターン

基本展開

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

${VAR}は環境変数の値に展開されます。未設定でデフォルトがない場合、Claude Codeは設定のパースに失敗してエラーをログに記録します。

デフォルト付き展開

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

${VAR:-default}はVARが未設定または空のときにdefaultを使用します。URLが設定可能だが多くのユーザーには適切なデフォルトがあるサーバーに適しています。

展開が機能する場所

環境変数展開は以下でサポートされます。

• command — サーバーの実行ファイルパス
• args — コマンドライン引数（各要素それぞれ）
• envの値 — キーではなく値のみ
• url — URL文字列全体
• headersの値 — キーではなく値のみ

展開されない場所: フィールド名（JSONオブジェクトのキー）、typeの値、ネストされたOAuth設定フィールド。

よくあるパターン

共有設定でユーザーごとのAPIキー:

{
  "mcpServers": {
    "stripe": {
      "type": "http",
      "url": "https://mcp.stripe.com/mcp",
      "headers": {
        "Authorization": "Bearer ${STRIPE_API_KEY}"
      }
    }
  }
}

チームメンバーはシェルプロファイルまたは.env.localにSTRIPE_API_KEYを設定します。共有の.mcp.jsonにクレデンシャルは含まれません。

環境別URL:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${INTERNAL_API_URL:-https://api.staging.example.com}/mcp"
    }
  }
}

本番環境はINTERNAL_API_URL=https://api.example.comを設定します。それ以外の環境はステージングURLをデフォルトとして使用します。

セキュリティのベストプラクティス

allowedToolsとdeniedMcpServers

Claude Codeは設定システムを通じてMCPツールのパーミッションを公開します。プロジェクトでMCPサーバーからどのツールを使用可能にするかを制限できます。

.claude/settings.json内:

{
  "permissions": {
    "allow": ["mcp__filesystem__read_file", "mcp__filesystem__list_directory"],
    "deny": ["mcp__filesystem__write_file", "mcp__filesystem__delete_file"]
  }
}

パーミッションエントリはglobパターンを使用します。mcp__filesystem__*はfilesystemサーバーのすべてのツールを許可または拒否します。

組織向けには、管理対象設定のdeniedMcpServersで特定のサーバーのロードを完全にブロックします。

{
  "deniedMcpServers": [
    { "serverUrl": "https://untrusted-server.example.com/*" },
    { "serverCommand": ["npx", "-y", "suspicious-package"] }
  ]
}

デニーリストのエントリはURLパターン（*ワイルドカードサポート）、正確なコマンド配列、またはサーバー名でマッチします。

環境変数のスコーピング

.mcp.jsonの値にクレデンシャルを直接入れないでください。ファイルが.gitignoreにある場合でも、誤ってコミットするリスクがあります。常に${VAR}展開を使用してください。

// 悪い例 — 設定にクレデンシャル
{
  "env": {
    "API_KEY": "sk-live-abc123xyz"
  }
}

// 良い例 — 環境からクレデンシャルを取得
{
  "env": {
    "API_KEY": "${STRIPE_API_KEY}"
  }
}

チーム設定では、READMEまたは.env.exampleファイルに必要な環境変数を記載してください。

# .env.example
STRIPE_API_KEY=sk-...
GITHUB_PAT=github_pat_...
DATABASE_URL=postgresql://...

サーバーの信頼性とプロンプトインジェクションのリスク

すべてのMCPサーバーは原則的にClaudeをプロンプトインジェクションに晒す可能性があります——外部コンテンツ（issue、メール、ドキュメント）を取得する接続済みサーバーが、Claudeのアクションをリダイレクトしようとする作られたコンテンツを埋め込む場合があります。Anthropicのドキュメントはこのリスクを明確に述べています。

サーバーを接続する前に確認すること:

1. 既知の信頼できるソースから来ているか
2. どんな外部コンテンツを取得するかを理解しているか
3. リクエストするパーミッションをレビューしたか

.mcp.jsonのプロジェクトスコープのサーバーについて、Claude Codeは初めてロードする前に承認を求めます。このプロンプトには理由があります。プロジェクトサーバーを承認するとき、そのファイルで定義されたコマンドがマシン上で実行されることを信頼していることになります。

承認の選択をリセットするには: claude mcp reset-project-choices。

チーム向けmanaged-mcp.json

どのサーバーを実行するかを制御する必要のある組織は、managed-mcp.jsonをシステムパスに展開します。このファイルが存在すると排他的な制御権を持ち、ユーザーは追加のサーバーを追加できません。

// /Library/Application Support/ClaudeCode/managed-mcp.json (macOS)
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

managed-mcp.jsonにAPIキーを保存しないでください——ファイルはマシン上のすべてのユーザーが読み取れます。ユーザーごとの環境変数を使った${VAR}展開か、OAuthフローを使用してください。

設定問題のトラブルシューティング

サーバーが表示されない

次のコマンドでステータスを確認します。

claude mcp list
# ⏸ Pending approval または ✗ Rejected を確認

サーバーが承認待ちとして表示されている場合、インタラクティブなClaude Codeセッションを開始してプロジェクトスコープのサーバーの信頼プロンプトを受け入れてください。

サーバーがまったくリストされていない場合は設定にパースエラーがある可能性があります。次を確認してください。

• デフォルトなしの未設定環境変数: ${UNSET_VAR}はパース失敗を引き起こします
• 必須フィールドの欠如（stdioではcommand、httpではurl）
• 予約名workspace

サーバーはロードされるがツールが機能しない

Claude Codeセッション内で:

/mcp

これは各サーバーの接続状態とツール数を表示します。接続済みだが0ツールと表示されるサーバーは、接続はしたがツールを公表していないことを意味します——初期化要件についてサーバーのドキュメントを確認してください。

認証の失敗

HTTPサーバーの場合、headers.Authorizationを設定してサーバーが拒否した場合、Claude CodeはOAuthにフォールバックしません。接続を失敗とマークします。トークンがMCPエンドポイントに有効かどうかを確認する（REST APIだけでなく）か、headers.Authorizationを削除してOAuthフローを代わりに使用してください。

タイムアウトの問題

デフォルトのMCPツールタイムアウトはMCP_TOOL_TIMEOUT環境変数で設定されます。長時間の操作（大規模なデータベースクエリ、ブラウザ自動化）を行うサーバーにはサーバーごとのタイムアウトを設定します。

{
  "mcpServers": {
    "browser": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "timeout": 120000
    }
  }
}

timeoutの値はツール呼び出しあたりのミリ秒です。HTTPサーバーでは、この値に関わらず最初のバイトのバジェットは最小60秒であることに注意してください。

接続失敗時の指数バックオフ

HTTPとSSEサーバーは切断時に自動的に再接続します。Claude Codeは指数バックオフで最大5回再試行します（1秒、2秒、4秒、8秒、16秒）。初期接続の失敗については、一時的なエラー（5xx、接続拒否、タイムアウト）で最大3回再試行します。認証エラーと404は再試行されません——設定の修正が必要です。

再接続中、サーバーは/mcpでペンディングと表示されます。5回の試行が失敗した後は失敗とマークされます。/mcpから手動で再試行できます。

大きなツール出力の警告

ツールが10,000トークン以上を返すとClaude Codeは警告を表示します。デフォルトの上限は25,000トークンです。MAX_MCP_OUTPUT_TOKENS環境変数で上限を上げます。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

MCPサーバーを作成していて、特定のツールが正当に大量の結果（完全なデータベーススキーマ、ファイルツリー）を返す場合、tools/listレスポンスでそのツールにアノテーションを付けてください。

{
  "name": "get_full_schema",
  "description": "Returns the complete database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

これにより、ユーザーがグローバルな環境変数を変更することなく、そのツール専用の閾値が最大50万文字の上限まで上がります。

サーバーの詳細を確認する

Claude CodeがサーバーをどのようにストアしているかをOAuth設定を含めて正確に検査するには:

claude mcp get <server-name>

トランスポートタイプ、URLまたはコマンド、設定されたヘッダー（リダクション済み）、OAuthステータスを表示します。サーバーが誤ってロードされているように見える場合、claude mcp getの出力と.mcp.jsonのエントリを比較してどのスコープの定義が優先されているかを確認してください。

マイグレーション：claude_desktop_config.json から .mcp.json へ

2つのファイルはほぼ同一のJSON構造を使用します。マイグレーションは主にエントリの移動とファイルの場所の更新です。

Claude Desktopのフォーマット（~/Library/Application Support/Claude/claude_desktop_config.json）:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"],
      "env": {}
    }
  }
}

Claude Codeの.mcp.jsonフォーマット:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Documents"]
    }
  }
}

主な違い:

1. typeフィールド: Claude Codeは明示的なtypeフィールドを必要とします。Claude Desktopはcommandが存在するときにstdioを推測します。すべてのstdioサーバーエントリに"type": "stdio"を追加してください。

2. 空のenvオブジェクト: 設定する環境変数がない場合は"env": {}を省略してください。どちらでも有効ですが省略した方がすっきりします。

3. HTTPサーバー: Claude DesktopはバージョンによってリモートサーバーをChrome Desktopとは異なる方法でストアする場合があります。Claude Codeではすべてのリモートサーバーに明示的なtype: "http"またはtype: "sse"が必要です。

自動マイグレーション: 手動変換の代わりに次を使用してください。

claude mcp add-from-claude-desktop

これは形式の違いを自動的に処理し、インポートするサーバーを選択できます。

スコープの考慮: インポートされたサーバーはデフォルトでローカルスコープに入ります。チームと共有するにはプロジェクトルートの.mcp.jsonに結果エントリをコピーし、今後のclaude mcp addコマンドに--scope projectを追加してください。

FAQ

.mcp.jsonはClaude Desktopで使えますか？

いいえ。Claude Desktopは独自のアプリケーションサポートディレクトリからclaude_desktop_config.jsonを読み取ります。2つのアプリケーションは別々の設定ファイルを管理します。claude mcp add-from-claude-desktopを使ってClaude DesktopからClaude Codeにサーバーをコピーしてください。

.mcp.jsonにユーザースコープのサーバーと同じ名前のサーバーがある場合はどうなりますか？

ローカルスコープまたはユーザースコープの定義が優先されます。Claude Codeは各サーバー名の1つのインスタンスに接続し、最も高い優先順位の定義を使用します。エントリ全体がそのスコープから使用されます——フィールドはマージされません。claude mcp listを使ってどのエントリがアクティブかを確認してください。

APIキーをenvの値に入れて.mcp.jsonをコミットできますか？

できますが、すべきではありません。リポジトリへのアクセス権を持つ誰でもファイルを読み取れます。${ENV_VAR}展開を使い、チームメンバーがシェルプロファイルまたは（.gitignoreに入れた）.env.localに自分のクレデンシャルを設定するようにしてください。

チェックインせずに1つのプロジェクトだけのサーバーを追加するには？

ローカルスコープ（デフォルト）を使ってください: claude mcp add --transport http myserver https://...。これはサーバーを現在のプロジェクトパス配下の~/.claude.jsonに保存します。他の誰にも見えず、.mcp.jsonには表示されません。

Claude Desktopでは接続されるがClaude Codeで失敗します。なぜですか？

最も一般的な原因は欠落または誤ったtypeフィールド、またはClaude Codeが動作する環境のPATHにないcommandです。Claude Desktopとclaude Code CLIは異なるPATH値で実行される場合があります。commandの値にはフルパスを使うか、claudeを実行するターミナルでwhich npx/which python3で確認してください。

サーバー設定のtimeoutとMCP_TOOL_TIMEOUTの違いは？

MCP_TOOL_TIMEOUTはすべてのMCPツール呼び出しのデフォルトタイムアウトを設定するグローバルな環境変数です。サーバーの.mcp.jsonエントリのtimeoutフィールドはそのサーバーのみMCP_TOOL_TIMEOUTをオーバーライドします。1つのサーバーの長時間実行操作と他の高速タイムアウトが必要な場合は、サーバーごとにtimeoutを設定してください。

プロジェクトでMCPを完全に無効にできますか？

個々のユーザーは関連する設定ファイルからすべてのMCPサーバーエントリを削除できます。組織向けには、空のmcpServersオブジェクトを持つmanaged-mcp.jsonを展開してください——これにより任意のMCPサーバーのロードを防ぎ、claude mcp addをブロックします。

関連記事

• Claude Code MCPサーバー完全ガイド（2026年版）
• Claude Codeスキルの書き方（2026年版）
• ルールギャラリーを見る