この記事でわかること
- Claude Code に MCP（Model Context Protocol）サーバーを接続する具体的なコマンドと手順
local/project/userという3つの接続スコープの違いと、チームで共有すべき場面の見分け方- リモートサーバーに多い OAuth 認証の実際の流れと、つまずきやすいポイント
- 日本の開発環境（社内プロキシ、英語ドキュメント前提の設計）で接続する際に事前に知っておくべき注意点
MCP は、Claude Code のようなツールをデータベースや外部サービスに接続するためのオープンな標準規格です。設定ファイルを1つ書けば動く場合もあれば、認証まわりで数分詰まる場合もあります。この記事では、公式ドキュメントで示されているコマンド体系を軸に、実際に設定を進める際に見落としやすい点を整理します。
MCPとは何か、Claude Codeでなぜ使うのか
MCP（Model Context Protocol）は、AI アプリケーションを外部のデータソースやツールに接続するためのオープンソースの標準規格です。Model Context Protocol 公式サイトでは「AIアプリケーションのためのUSB-Cポートのようなもの」と説明されており、Claude Code や Claude Desktop、ChatGPT など複数のクライアントが同じ規格を使ってサーバーに接続できる点が特徴です。
Claude Code の文脈で言えば、MCP を使う動機は「チャットに手作業でデータを貼り付ける作業をなくすこと」に集約されます。Issue トラッカーのチケット内容をコピーして貼り付けるのではなく、GitHub や Jira の MCP サーバーに直接接続すれば、Claude Code がその場でチケットを読みに行けます。データベースのスキーマを説明する代わりに、読み取り専用の DB 接続を渡せば、Claude Code 自身がスキーマを確認しながら作業できます。この「貼り付けるかわりに直接読みに行かせる」という発想が、接続先を選ぶときの基本的な判断軸になります。
接続方法の全体像
接続作業は、サーバーの種類を決めてから登録し、必要なら認証する、という流れで進みます。全体の流れは次の通りです。
ポイントは、claude mcp add が成功してもそれは「設定が書き込まれた」ことの確認にすぎず、実際に接続できたかどうかは claude mcp list や /mcp パネルで別途確認する必要があるという点です。Claude Code の MCP 接続ドキュメントにも明記されている通り、claude mcp add は資格情報を検証しないため、誤ったトークンを渡しても登録自体は通ってしまいます。
スコープを理解する — local / project / user
MCP サーバーは3つのスコープのいずれかで登録され、それぞれ保存先と共有範囲が異なります。個人用の実験的な接続を project スコープで登録してしまうと、意図せずチーム全員の環境に配信されることになるため、最初にこの違いを押さえておく価値があります。
project スコープは .mcp.json をリポジトリにコミットしてチーム全員に同じ接続を配る用途に向いていますが、セキュリティ上の配慮として、Claude Code は .mcp.json 由来のサーバーを使う前に承認プロンプトを出します。逆に、個人のAPIキーを使うような接続は local（既定値）か user に留め、リポジトリに書き込まないのが安全です。
実際に接続してみる — stdio と HTTP の基本コマンド
リモートの MCP サーバーは HTTP 経由で接続するのが現在推奨されている方式です。
“bash claude mcp add --transport http notion https://mcp.notion.com/mcp “
一方、ローカルのプロセスとして動くサーバー（npx 経由で起動するものなど）は stdio で接続します。この場合、Claude Code 自身のオプションとサーバーに渡す引数を -- で区切る必要があります。
“bash claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server “
-- を省略すると、サーバー側の引数（たとえば --port のようなフラグ）を Claude Code 自身のオプションとして解釈しようとしてエラーになります。これは stdio 接続でもっとも踏みやすい落とし穴の一つです。
実際に試してわかったこと
ドキュメント通りに手を動かすと、いくつか「読んだだけでは気づきにくい」挙動に当たります。まず、claude mcp add がエラーなく Added ... を返しても、それは設定ファイルへの書き込みが成功しただけで、実際の疎通確認ではありません。GitHub の連携例のように、プレースホルダーのトークンを渡しても登録自体は成功し、失敗が判明するのは /mcp で failed 表示を見たときです。登録後は必ず claude mcp list か /mcp で状態を確認する、という一手間を挟む前提で作業を組んだほうが手戻りが少なくなります。
もう一つは環境変数展開の挙動です。.mcp.json では ${VAR} や ${VAR:-default} の形式で環境変数を展開できますが、参照先の変数が未設定でもエラーにはならず、${VAR} という文字列のまま設定が読み込まれてしまいます。気づかずに放置すると、認証ヘッダーに変数名の文字列がそのまま入った状態で接続を試み続けることになるため、claude mcp list に出る missing-variable の警告を見落とさないようにする必要があります。
さらに、project スコープのサーバーはクローンしたばかりのリポジトリでは承認待ち（Pending approval）のまま止まります。CI や新しい開発環境で「なぜかサーバーに繋がらない」と感じたら、認証情報の前に、まずそのフォルダを信頼済みにする操作が済んでいるかを疑う価値があります。
日本で使う場合の注意
サーバー名に使える文字は、公式ドキュメント上で「英字・数字・ハイフン・アンダースコアのみ」と明記されています。日本語や全角文字を含む名前は登録時にエラーになるため、notion-jp のように英数字で名前を設計する必要があります。Claude Desktop からインポートする場合も、スペースなどの非対応文字を含む名前はスキップされる仕様なので、命名規則は最初から意識しておいたほうが手戻りが少なくなります。
もう一点、OAuth 認証はブラウザでのログインとローカルのコールバック（http://localhost:PORT/callback）を前提にしています。社内ネットワークやVPN経由で開発している場合、ループバックアドレスへのリダイレクトがプロキシやファイアウォールの設定によって塞がれることがあります。うまく繋がらないときは、まずMCPサーバー側の設定ではなく、ローカルポートへの通信が経路上でブロックされていないかを確認する方が早く原因にたどり着けます。加えて、npx 経由で起動する stdio サーバーはパッケージ取得のたびに外部レジストリへ通信するため、社内プロキシ配下では HTTPS_PROXY などの環境変数が正しく引き継がれているかも合わせて確認しておくと安全です。
まとめ
Claude Code への MCP 接続は、claude mcp add でスコープと接続方式を指定し、必要なら /mcp で認証を済ませ、最後に claude mcp list で状態を確認する、という3ステップに集約されます。つまずきやすいのはコマンドの構文そのものより、スコープの選び間違いや、登録は成功しても実際には未接続という状態を見逃すことです。まずは個人利用の local スコープで1つサーバーを繋いでみて、/mcp で Connected の表示を確認するところから始めるのが安全な進め方です。チームで共有する段階になったら、.mcp.json をリポジトリに追加する前に、承認フローとサーバー名の命名規則を一度チームで確認しておくとよいでしょう。
