Claude Code MCP 完全ガイド：MCP サーバーの追加・設定・管理

Claude Code は MCP サーバーにどう接続するのか

Claude Code は claude mcp add コマンドで MCP サーバーに接続します。リモートサーバーなら --transport http と URL を、ローカルの stdio サーバーなら -- の後ろに起動コマンドを書きます。各サーバーは 3 つのスコープ（local・project・user）のいずれかに保存され、セッション内の /mcp メニューで状態確認、ログイン、再接続を行います。

このガイドでは上の説明を一つずつ掘り下げます。コマンドはすべて公式の Claude Code MCP ドキュメントと照合済みです。まずは何かつないでみたいという方は、先に MCP サーバーディレクトリをのぞいてみてください。

クイックリファレンス

ステップ 1：トランスポートを選ぶ

MCP サーバーには大きく 2 つの形があり、Claude Code はどちらにも対応しています。

リモート HTTP サーバー（推奨）

ホスト型サーバーの多くは Streamable HTTP エンドポイントを公開しています。--transport http で URL を渡します：

claude mcp add --transport http notion https://mcp.notion.com/mcp

OAuth ではなく API キーを使うサーバーなら、ヘッダーで渡します：

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

2 つ目の例は、Fine-grained 個人アクセストークンを使う GitHub MCP サーバーです。claude mcp add は認証情報を検証せずに設定を保存するため、トークンが間違っていても後で接続失敗として現れるだけだという点に注意してください。

リモート SSE サーバー（非推奨）

古いサーバーの中には今も Server-Sent Events を使うものがあります。SSE トランスポートは MCP 仕様では非推奨ですが、Claude Code は引き続きサポートしています：

claude mcp add --transport sse asana https://mcp.asana.com/sse

ドキュメントによると、最近のバージョンの Claude Code では、SSE 専用のエンドポイントに --transport http を指定した場合も自動的に SSE へフォールバックします。

ローカル stdio サーバー

stdio サーバーは Claude Code があなたのマシン上で起動するプロセスで、通常は npx、uvx、またはバイナリで動かします。-- 区切りの後ろはすべてそのままサーバーに渡されます：

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

次の 3 つのルールを守れば、stdio のミスはほとんど防げます：

• Claude Code 自身のオプション（--transport、--env、--scope、--header）は -- 区切りの前に書く。
• サーバー向けのフラグ（npx の -y や --port 8080 など）は -- の後ろに書く。
• --env は複数の KEY=value を受け付けます。サーバー名を --env の直後に置くと、CLI はその名前を別のペアとして読み取りエラーになるため、間に --transport stdio などの別のオプションを挟みます。

短縮形もあります：-t は --transport、-e は --env、-H は --header、-s は --scope です。

ステップ 2：スコープを選ぶ

追加したサーバーはどれか 1 つのスコープに属します。デフォルトは local です。

実際に使ってみて役立つ目安：

• local：個人的な試用や、自分の認証情報を含むもの。
• project：リポジトリをクローンしたチーム全員が使うべきサーバー。たとえばドキュメント用サーバーや、UI テスト用の Playwright MCP サーバー。
• user：どこでも使いたいツール。たとえば最新のライブラリドキュメントを提供する Context7。

同じ名前のサーバーが複数のスコープにある場合、local が project より、project が user より優先されます。採用されるのは勝ったスコープのエントリ全体で、フィールドはマージされません。

ステップ 3：.mcp.json でサーバーを共有する

--scope project でサーバーを追加すると、プロジェクトルートに次のようなファイルが作られます：

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

.mcp.json を手で編集してコミットしても構いません。注意点は 2 つです：

• url だけで type のないエントリは stdio として読まれ、失敗します。リモートサーバーには必ず "type": "http"（または "sse"）を書きます。
• 対話セッションでは、Claude Code はプロジェクトのサーバーを使う前に承認を求めます。クローンしたリポジトリが自分自身のサーバーを承認することはできません。承認するまで claude mcp list ではそのサーバーが承認待ちと表示されます。承認をリセットするには claude mcp reset-project-choices を実行します。

環境変数でシークレットを git から切り離す

.mcp.json では command、args、env、url、headers の中で変数展開が使えます：

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

${VAR} は変数の値に展開され、${VAR:-default} は未設定時にデフォルト値を使います。変数が未設定でデフォルトもない場合、文字列がそのまま設定に残り、claude mcp list が警告を出します。トークンを安全に扱う方法は MCP セキュリティのベストプラクティスを参照してください。

ステップ 4：OAuth で認証する

多くのホスト型サーバー（Notion、Sentry、Linear など）は固定キーではなく OAuth を使います。サーバーを追加してから、Claude Code 内でログインします：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

claude を起動して /mcp と入力し、サーバーを選んでブラウザでログインを完了します。シェルから claude mcp login sentry でログインすることもでき（画面のないマシンでは --no-browser を付ける）、保存済みトークンは claude mcp logout sentry で消去できます。

知っておきたい制限：

• 非対話実行（claude -p）では OAuth を完了できません。先に対話セッションで一度ログインしておきます。
• 事前登録済みの OAuth アプリが必要なサーバーは、追加時に --client-id、--client-secret、--callback-port を指定できます。

このフローのプロトコル側の仕組みは MCP 認証と OAuth で解説しています。

ステップ 5：他のクライアント向けの手順からサーバーを追加する

README の多くは Claude Desktop や Cursor の設定しか載せていません。次のように読み替えます：

• URL ならリモートサーバー：claude mcp add --transport http name URL。
• npx -y @example/mcp-server のような起動コマンドなら stdio：claude mcp add name -- npx -y @example/mcp-server。
• mcpServers の JSON ブロックなら、外側のラッパーではなく中のオブジェクトを add-json に渡します。

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

add-json でも --scope user や --scope project が使えます。

Claude Desktop から取り込む

Claude Desktop ですでに動いているサーバーがあるなら、取り込めます：

claude mcp add-from-claude-desktop

対話式の選択画面で取り込むサーバーを選びます。この機能は macOS と WSL でのみ動作します。サーバー名に使えるのは英数字、ハイフン、アンダースコアだけなので、名前にスペースを含む Desktop のサーバーはスキップされ、重複する名前には server_1 のような接尾辞が付きます。

日常的な管理

claude mcp list          # 全サーバーと稼働状態
claude mcp get notion    # 1 つのサーバーの詳細
claude mcp remove notion # 削除（保存済みの OAuth トークンも削除）

セッション内の /mcp では各サーバーの状態とツールが表示され、再接続、再認証、削除せずに無効化することができます。表示される状態には ✔ Connected、! Needs authentication、✘ Failed to connect、⏸ Pending approval などがあります。

コンテキスト消費とツール検索

ツール検索はデフォルトで有効です。Claude Code は起動時にツール名だけを読み込み、Claude が必要としたときに完全な定義を取得するため、サーバーを増やしてもコンテキストウィンドウへの影響はわずかです。毎ターン使う小さなサーバーは、エントリに "alwaysLoad": true を設定すると最初から読み込まれます。遅延読み込みを完全に無効にするには ENABLE_TOOL_SEARCH=false claude で起動します。クライアントがツールを見つける仕組みについては MCP ツールディスカバリーをご覧ください。

リソースとプロンプト

サーバーは @ で参照できるリソース（例：@github:issue://123）や、/mcp__servername__promptname の形でスラッシュコマンドとして現れるプロンプトを公開できます。サーバーが何を公開しているか分からない場合は MCP のリソースとツールの違いを参照してください。

トラブルシューティング

stdio サーバーがクラッシュしたら、まずそのコマンドをターミナルで直接実行して確かめます。リモートサーバーの挙動がおかしいときは、MCP Inspector で実際の応答を確認できます。なお、stdio サーバーは自動では再接続されないので、/mcp から再接続してください。

Claude Code におすすめの MCP サーバー

ブラウザサーバーについては、専用の Playwright MCP の Claude Code セットアップガイドを参照してください。

次のステップ

今週本当に使うサーバーを 1 つ選び、local スコープで追加して、/mcp で ✔ Connected と表示されることを確認してから次を追加しましょう。役に立つと分かったら project スコープに移して、チームでも使えるようにします。ほかのサーバーは MCP サーバーディレクトリを見るか、カテゴリで絞り込んで探してください。