Claude Code に MCP サーバーを追加する（claude mcp add、.mcp.json、スコープ）

リモートサーバーには HTTP トランスポートが推奨です。stdio サーバーはマシン上のローカルプロセスとして実行されます。stdio では、-- 区切りによって Claude 自身のオプション（--transport、--env、--scope など）とサーバー起動コマンドを分けます。-- 以降はすべてそのままサーバーに渡されます。

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP server with a Bearer token header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Local stdio server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• 環境変数は -e または --env で設定します。例: -e KEY=value。
• --env の直後にサーバー名を置くと、CLI は名前を別のペアとして読み取り、拒否します。--env と名前の間に --transport stdio などの別のオプションを入れてください。
• --transport と --header は短縮形 -t と -H も使えます。
• SSE は非推奨です。SSE のみのサーバーに接続するには、引き続き --transport sse を渡せます。
• サーバーの JSON 設定がすでにある場合は、claude mcp add-json NAME 'JSON' で追加します。

-s または --scope で 3 つのスコープから 1 つを選びます。Local（デフォルト）は現在のプロジェクトでのみ読み込まれ、~/.claude.json に保存されます。Project はプロジェクトルートの .mcp.json に保存されるため、バージョン管理を通じてチームに共有されます。User も ~/.claude.json に保存されますが、すべてのプロジェクトで読み込まれます。同じサーバー名が複数のスコープで定義されている場合、local が project より、project が user より優先されます。

claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

.mcp.json は command、args、env、url、headers で ${VAR} と ${VAR:-default} の展開に対応しています。リモートのエントリには必ず type を設定してください。Claude Code は type のないエントリを stdio サーバーとして扱うため、url があって type がないエントリは設定エラーになります。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-weather": {
      "type": "stdio",
      "command": "/path/to/weather-cli",
      "args": ["--api-key", "${WEATHER_API_KEY}"],
      "env": { "CACHE_DIR": "/tmp" }
    }
  }
}

• Claude Code は .mcp.json のプロジェクトスコープのサーバーを使う前に承認を求めます。その選択は claude mcp reset-project-choices でリセットできます。
• 参照された変数が未設定でデフォルトもない場合、サーバーはリテラルの ${VAR} テキストのまま読み込まれ、claude mcp list に警告が表示されます。

Claude Code はリモートサーバー向けに OAuth 2.0 に対応しています。サインインが必要なサーバーを追加したら、Claude Code 内で /mcp を実行し、ブラウザでログインを完了します。トークンは安全に保存され、自動で更新されます。アクセスを取り消すには、/mcp メニューの Clear authentication を使います。

claude mcp list
claude mcp get notion
claude mcp remove notion
claude mcp login sentry
claude mcp logout sentry

リモートサーバーを削除すると、Claude Code が保存したそのサーバーの OAuth トークンも削除されます。1 つのスコープから定義を削除するには、claude mcp remove NAME --scope SCOPE を実行します。

• MCP_TIMEOUT はサーバー起動のタイムアウトをミリ秒で設定します。例: MCP_TIMEOUT=10000 claude。
• MCP_TOOL_TIMEOUT はツール実行のタイムアウトを設定します。サーバーごとに上書きするには、そのサーバーの .mcp.json エントリに timeout フィールド（ミリ秒）を設定します。
• Claude Code は MCP ツールの出力が 10,000 トークンを超えると警告し、デフォルトでは 25,000 トークンで打ち切ります。上限は MAX_MCP_OUTPUT_TOKENS で引き上げられます。

export MAX_MCP_OUTPUT_TOKENS=50000
MCP_TIMEOUT=10000 claude