【ITニュース解説】Claude Code MCP Deep Dive (2): From a Configuration Entry to a Handshake

Claude Codeという開発ツールが、Model Context Protocol（MCP）サーバーという外部システムと接続して機能を利用するまでの過程は、単純なものではなく、いくつかの段階を経て実現される。特に重要なのは、サーバーの情報を正しく設定し、その設定に基づいて実際にサーバーと通信し、利用可能な機能を確認する、という流れである。

MCPサーバーに接続するには、まずそのサーバーがClaude Codeの設定ファイルに登録されている必要がある。この設定の仕方にはいくつかの種類があり、誰がそのサーバーを使うのか、そしてどの情報を共有できるかによって適切な方法を選ぶ。例えば、会社で使うJiraサーバーをMCPサーバーとして利用する場合を考えてみよう。チーム全員がそのサーバーを使えるようにしたいが、個人のAPIトークン（認証情報）は共有したくない、という状況がよくある。MCPはこの問題を解決するために、共有される接続情報と個人の秘密情報を別々に管理できる仕組みを提供する。

Claude Codeの設定は主に四つの異なる「スコープ」で管理される。一つ目は「プロジェクトスコープ」で、これはプロジェクトのルートディレクトリにある.mcp.jsonというファイルに記述される。このファイルはバージョン管理システム（Gitなど）にコミットできるため、チーム全体でサーバーの名前、接続先（エンドポイント）、起動方法などの基本的な情報を共有できる。ただし、個人の認証情報のような秘密の情報はここには含めない。二つ目は「ユーザースコープ」で、これはユーザーのホームディレクトリにある~/.claude.jsonというファイルに記述される。この設定はそのユーザーが扱うすべてのプロジェクトに適用されるため、特定のプロジェクトに紐付かない、個人的に便利なサーバーの情報を設定するのに適している。三つ目は「ローカルスコープ」で、これも~/.claude.jsonファイルに記述されるが、特定のプロジェクトに紐付く点がユーザースコープと異なる。この設定はプライベートに保たれ、他のプロジェクトを開いたときには表示されない。Jiraサーバーの例で言えば、プロジェクトの.mcp.jsonファイルで「このリポジトリはJiraサーバーを使う」と宣言しつつ、各開発者は自分のAPIトークンなどの個人認証情報をこのローカルスコープで秘密裏に設定する、といった使い方ができる。共有されたプロジェクト設定が統合の土台を作り、ローカル設定が各個人にとっての完全な接続を可能にするわけだ。最後に「組織管理スコープ」があり、これは組織の管理者が一元的にサーバー設定を提供し、個々のユーザーはその設定を直接編集することはない。これらは主要なスコープだが、コマンドラインオプションで一時的な設定をしたり、Claude.ai経由でコネクタを設定したりする特別なパスも存在する。

もし同じ名前のサーバーが複数のスコープで定義された場合、Claude Codeは明確な優先順位に基づいてどの設定を使うかを決定する。その優先順位は次の通りである: 最も優先されるのがローカルスコープの設定で、次にプロジェクトスコープ、その後にユーザースコープが続く。さらに、プラグインが提供するサーバー定義、そしてClaude.aiコネクタの順となる。組織管理サーバー定義は、これらのどれよりも高い優先順位を持つ。ここで重要なのは、Claude Codeが個々の設定フィールドをマージするのではなく、優先順位の高いスコープからサーバー設定の全体を採用するという点である。例えば、ローカルスコープとプロジェクトスコープの両方に同じ名前のサーバー定義があった場合、ローカルスコープの設定が完全に採用され、プロジェクトスコープの追加情報と組み合わせられることはない。この仕組みによって、開発者がデバッグする際にどの設定が使われているのかを明確に理解できるようになる。この優先順位は実用性を考慮して定められており、チームが共有の基準を設定しつつ、個人が独自の定義でそれを上書きできる柔軟性を提供している。また、プロジェクトスコープのサーバーについては、リポジトリと一緒に配布されることが多いため、Claude Codeは最初に使う際にユーザーに承認を求めることで、不審な接続が勝手に行われるのを防ぐ安全策が講じられている。

しかし、設定情報が整っただけでは、そのサーバーが実際に利用可能になったわけではない。設定はあくまで「このサーバーを試すべきだ」という宣言に過ぎず、実際の接続はこれから確立される。Claude Codeはサーバーの接続状態を単一の「はい／いいえ」だけで判断するのではなく、「接続済み」「接続失敗」「接続中」「無効」「認証が必要」といった詳細な状態を区別して追跡する。この区別は非常に重要である。なぜなら、「サーバーに到達できない」という問題と「サーバーには到達できるが認証に失敗した」という問題では、根本的な原因も解決策も全く異なるからだ。URLが間違っている、プロセスが起動していないといった場合は接続の問題であり、OAuthセッションの期限切れや権限不足は認証の問題となる。これらを区別せずに同じ「失敗」として扱ってしまうと、次に取るべき適切な行動が見えなくなってしまうだろう。また、接続を確立する際のタイムアウトと、接続後にサーバーに何か処理を依頼する際のタイムアウトも異なる期待値を持つべきだ。接続が短い時間内に応答しない場合は設定ミスやサーバーが動いていない可能性が高いが、サーバーが重い処理を実行している場合は長い時間かかることもあるため、両者を同じ失敗と見なすのは適切ではない。

接続が無事に確立できたとしても、まだ終わりではない。Claude Codeは次に、そのサーバーが実際にどのような機能（Capability）をサポートしているのかを知る必要がある。このプロセスを「能力ネゴシエーション」と呼ぶ。クライアント（Claude Code）とサーバーが互いにサポートする機能を宣言し合い、クライアントはサーバーが実際に広告（通知）してきた機能のみを有効にする。あるサーバーは「ツール」を提供するが「リソース」は提供しないかもしれないし、別のサーバーは読み取り可能な「リソース」だけを提供し、「ツール」は全く提供しないかもしれない。MCPは単に「ツールを追加する方法」として説明されることもあるが、実際には「ツール」「リソース」「プロンプト」といった異なる機能のファミリーをサポートしている。この能力ネゴシエーションのおかげで、Claude Codeはサーバーがサポートしない機能を無理に呼び出すような無駄な試みをせず、サーバーが実際に提供すると言っている機能だけを利用することで、柔軟かつ堅牢な連携を実現する。例えば、サーバーがツールを広告しないのであれば、Claude Codeはツールリストを要求しないし、リソースをサポートしないのであれば、リソース読み取り機能はそのサーバーに対しては利用不可となる。結果として、サーバーがサポートすると言っている機能だけを使うという、意図的に控えめなルールが適用される。

ハンドシェイクと能力ネゴシエーションが完了すれば、サーバーは「接続済み」の状態になる。しかし、これだけではClaude Codeがすぐにそのサーバーの新しいアクションを使えるようになるわけではない。接続によって確立されるのは、あくまで「動作可能な通信チャネル」と「両者で合意された機能セット」に過ぎない。次に必要となるのは、そのチャネルを通してどのようにデータが送受信されるのか、そしてサーバーが提供すると宣言したツールが、Claude Code自身のツールリストにどのように表示され、利用可能になるのか、という課題だ。これらはさらに別の変換プロセスであり、これらを分離して考えることがシステムを管理しやすくする鍵となる。具体的には、まず設定によって使用するサーバーの候補が選択され、次に接続とハンドシェイクによって利用可能な関係が確立される。その上で、能力ネゴシエーションによって、その関係で何ができるかが制限される。そして、これらの下層の準備が整った後に、さらに上位のレイヤーが、許可された能力をエージェント（AIモデルなど）に対して実際に公開する、という流れになる。

この接続プロセス全体を通して、Claude Codeがサーバーとどのように通信するのかという点は重要である。これは、ローカルで子プロセスを起動して標準入出力で通信するかもしれないし、ネットワーク越しにリモートサービスへリクエストを送るかもしれない。次回の解説では、この「トランスポートの選択」について、プロトコルが標準化している接続パスやClaude Codeが実際にサポートしているパス、そしてローカルプロセスとリモートサービスでの再試行や診断方法の違いについて詳しく見ていく。