Claude CodeでMCPサーバーを設定するとき、多くの人が最初に迷うのが「どのスコープで追加するか」と「認証（OAuth）が通らない」という2点です。設定コマンド自体はclaude mcp addの一行で終わりますが、追加したサーバーがチームに共有されるか・どこに保存されるか・認証をどう通すかを理解していないと、後から「他のプロジェクトでツールが見えない」「401エラーで接続できない」といったつまずきに直面します。この記事では、実際にClaude CodeでMCPサーバーを設定する手順を、local/project/userの3つのスコープの違いとOAuth認証のつまずき対処に絞って解説します。
MCPサーバーとは｜Claude Codeで何ができるようになるか
MCPが解決するのは「外部ツールとの接続」
MCP（Model Context Protocol）は、Claude CodeのようなAIクライアントが、外部のツール・データベース・APIに統一的な方法で接続するためのオープン標準です。Claude Code自身はMCPクライアントとして動作し、GitHub・データベース・ブラウザ操作などの機能を提供するMCPサーバーに接続します。設定してしまえば、Claude Codeのチャットからそのまま「GitHubのIssueを一覧して」「このDBのスキーマを確認して」といった操作が可能になります。
設定の全体像は3ステップ
MCPサーバーの設定は、大きく次の3ステップに分かれます。この記事はステップ2とステップ3でつまずく点を中心に扱います。
- ①追加：
claude mcp addでサーバーを登録する（スコープを選ぶ） - ②認証：必要ならOAuthなどで接続を認可する
- ③確認：
/mcpで接続状態とツール一覧を確認する
claude mcp addの基本手順
コマンドの構造
MCPサーバーを追加する基本コマンドは次の形です。--transportで接続方式（http・sseなど）、--scopeで保存先を指定し、その後にサーバー名とURLを続けます。
claude mcp add --transport http --scope local my-server https://your-mcp-server.example.com
環境変数を渡したい場合は--env KEY="value"を追加します。ローカルで動くコマンド型のサーバー（stdio）を追加する場合は、URLの代わりに起動コマンドを指定します。
追加後は必ず/mcpで状態を確認する
追加が終わったら、Claude Codeのセッション内で/mcpを実行します。ここで各サーバーの接続状態（connected / needs authentication など）と、利用可能になったツールの一覧が表示されます。「追加できた＝使える」ではなく、ここで接続状態が緑になっているかを確認するのが、つまずきを早期に発見するコツです。
スコープの違いを理解する｜local・project・user
3つのスコープの意味
Claude CodeのMCPサーバー設定には、保存先と共有範囲を決める「スコープ」が3種類あります。ここを取り違えると「自分の別プロジェクトでツールが見えない」「チームに設定が共有されない」といった混乱が起きます。
- local（デフォルト）：いま作業中のプロジェクトで、自分だけが使える。個人設定に保存され、Gitにはコミットされない。
- project：プロジェクト直下の
.mcp.jsonに保存され、チーム全員で共有できる。Gitにコミットして配布する前提。 - user：自分のすべてのプロジェクトで横断的に使える（旧称はglobal）。
保存先ファイルの違い
localとuserスコープの設定は各マシンのユーザー設定ファイル（~/.claude.json）に保存され、マシン間では同期されません。一方、--scope projectを指定した場合はプロジェクトルートの.mcp.jsonに書き込まれ、これをGitにコミットすればチーム全員が同じ設定を取得できます。
独自まとめ｜スコープ選択の判断表
どのスコープを選ぶべきかは「誰と共有したいか」で決まります。実際の使い分けを判断表にまとめました。迷ったらこの表で該当する行を選んでください。
| やりたいこと | 選ぶスコープ | 保存先 | Gitに含める？ |
|---|---|---|---|
| 自分だけ・このプロジェクト限定で試す | local（デフォルト） | ~/.claude.json | 含めない |
| チーム全員で同じサーバーを使う | project | .mcp.json | 含める（秘密情報は除く） |
| 自分の全プロジェクトで共通利用する | user | ~/.claude.json | 含めない |
| APIキーなど秘密情報を含む設定 | local または user | ~/.claude.json | 絶対に含めない |
判断のコアは「秘密情報はコミットしない」という一点です。projectスコープの.mcp.jsonは共有前提なので、そこに書けるのはURLやクライアントIDなど公開してよい設定に限ります。APIキーやトークンは環境変数やlocal/userスコープに逃がすのが安全です。
OAuth認証でつまずく点と対処
認証が必要なサーバーの見分け方
クラウド型のMCPサーバーの多くはOAuth認証を要求します。Claude Codeは、サーバーが401 Unauthorizedまたは403 Forbiddenを返したときに「認証が必要」と判断し、/mcpの一覧でそのサーバーに認証待ちのフラグを立てます。Claude CodeにはOAuth 2.1のサポート（PKCEによる認可コードフローとユーザー同意）が組み込まれており、ブラウザベースの認証フローでトークンの取得と管理を自動的に行います。
つまずきやすいポイントを表で整理
MCP設定でよく起きるつまずきと、その原因・対処を実際の状況ベースで表にまとめました。
| 症状 | 考えられる原因 | 対処 |
|---|---|---|
| 他のプロジェクトでツールが見えない | localスコープで追加した | 横断利用したいならuserスコープで追加し直す |
| チームに設定が共有されない | local/userで追加し.mcp.jsonに書かれていない | --scope projectで追加し.mcp.jsonをコミット |
| 401/403で接続できない | OAuth認証が未完了 | /mcpから認証フローを実行しブラウザで許可 |
| 認証しても接続が緑にならない | トークン失効、または設定URLの誤り | サーバーを削除して再追加し、URLと認証を再実行 |
| .mcp.jsonをコミットしたら情報漏れが心配 | 秘密情報を直書きした | キーは環境変数へ。共有するのはURL・クライアントIDのみ |
チーム共有時の認証は各自で行う
projectスコープで.mcp.jsonを共有する場合でも、OAuth認証は各メンバーが自分の環境で個別に完了する必要があります。共有すべきなのはURLやクライアントIDなど共通設定だけで、アクセストークンなどの秘密情報はリポジトリにコミットしないでください。これはClaude Code公式ドキュメントでも明記されている運用です。
設定を確認・修正する手順
一覧・削除・再追加の流れ
設定を間違えたときは、いったん削除して追加し直すのが確実です。claude mcp listで登録済みサーバーを確認し、不要なものはclaude mcp removeで削除します。スコープを間違えて追加してしまった場合も、削除してから正しいスコープで再追加する流れになります。
迷ったら公式ドキュメントを確認する
MCPの仕様やClaude Code側の対応は更新が続いています。スコープの扱いや認証フローの詳細は、Claude Code公式ドキュメント（Connect Claude Code to tools via MCP）を一次情報として確認するのが確実です。本記事の手順も同ドキュメントの内容を実際に確認してまとめています。
まとめ｜スコープと認証を押さえれば設定は難しくない
Claude CodeのMCPサーバー設定でつまずく点は、ほぼ「スコープの取り違え」と「OAuth認証の未完了」の2つに集約されます。claude mcp addの一行を打つ前に、その設定を自分だけで使うのか・チームで共有するのかを決めてスコープを選び、追加後は必ず/mcpで接続状態を確認する——この流れさえ守れば、設定作業でハマることはほとんどなくなります。秘密情報は.mcp.jsonにコミットしない、という一点だけは徹底しておきましょう。
Claude Code自体の始め方や料金プランの選び方から確認したい方は、Claude Codeの使い方｜始め方からつまずき対処・料金の選び方までもあわせてご覧ください。他のAIコーディングツールと比較して選びたい場合はAIコーディングツール比較5選、Claudeの拡張思考を使いこなしたい方はClaude 3.7 Sonnetの拡張思考の記事も参考になります。
