MCPサーバーの構造解析：OAuth、.well-knownディスカバリー、ツール設計

MCP OAuthは、当社のMCPサーバーにおいて、プロダクトの意図、プロトコルの健全性、そしてフィールドオペレーションの実状がまさに交錯する部分となりました。構築の目的は単にClaudeやChatGPTにツールを公開することだけではありませんでした。運用担当者がスケジューリングシステムを連携し、アクセス権限の経路を信頼した上で、どのアカウント、テナント、作業記録が実際に操作されているかを疑うことなくアシスタントを利用できるようにすることが重要だったのです。

本記事では、実稼働環境における構成を順を追って解説します。OAuthフロー、well-knownディスカバリー、ツールスキーマ、そしてフィールドオペレーションのワークフローが曖昧なチャット連携に終わらないようにするためのガードレールについて取り上げます。単に最初のファンクションコーリングが成功して終わるデモではなく、実際のプロダクト開発に近いMCPサーバーの実装例を求めているエンジニアやAI開発者に向けて執筆しています。

背景

Crisphiveにおいて、MCPサーバーは対話型クライアントと配車担当者が日常的に依存している運用システムとの間に位置します。つまり、このサーバーには2つの役割があります。エージェントにとって理解しやすいものであること、書籍の予約やスケジュールの閲覧、案件の更新、技術者のルート決定の調整といったビジネスアクションに対して慎重であることです。

このサーバーに求められた要件は、「AIエージェント用のツールAPIを作成する」といった漠然としたものよりも限定的なものでした。ツールが実行される前にアカウントの所有権を処理した上で、当社のスケジューリングや配車アクションを明確に表現できるリモートインターフェースが必要だったのです。OAuthを採用したのは、ユーザーにとって馴染みのある承認経路を提供でき、テナントを考慮したアクセス制限の明確な境界を確立できるからです。

もう1つの入り口はディスカバリーです。開発者が個別のアシスタントごとに独自の設定手順を記載しなくても、クライアント側でサーバーの所在、認証の仕組み、利用可能なツールを把握できる必要があります。ここで重要になるのがwell-knownディスカバリーです。これにより、接続の手順が不確実なやり取りではなく、予測可能な規約へと変わります。

この視点を持つことで、MCP OAuthのコストについても客観的に捉えることができました。コストとは単に実装にかかる時間だけではありません。ユーザーが誤ったワークスペースを連携してしまったり、トークンの有効期限切れの処理がうまくいかなかったり、ツールの説明文のせいでモデルが意図しない権限まで推測してしまうような、将来生じうるあらゆるエッジケースも含まれます。

仕組み

実稼働フローは、まずクライアントがMCPサーバーのメタデータをディスカバリーすることから始まり、フィールドオペレーションのツールがテナントデータにアクセスする前にユーザーを認証手順へと案内します。各要素は意図的にシンプルな構成となっています。検出可能なサーバー、OAuthに基づく接続、スコープ限定されたアクセス権限、そしてアクションが受け取る情報と返す情報を正確に規定するツールスキーマです。

OAuthが身元確認と同意を担当し、MCPレイヤーがツールの規約を担当します。書籍の予約や権限設定を行うアプリケーションレイヤーが、連携されたユーザーに何を許可するかを決定します。これらの関心事を分離することが、設計における最初の重要な選択でした。リクエストが到達した際、サーバーはテキストの指示から権限を再解釈するのではなく、認証されたアカウント、選択されたワークスペース、およびツールの引数をプロダクトのルールに照らし合わせてチェックすべきです。

ツールの設計こそが、連携が有用になるかリスクになるかを分けるポイントです。当社のMCPツール設計では、広範な「何でもできる」エンドポイントよりも、明確な入力を持つ限定的な操作を優先しています。スケジューリングアクションでは、案件、技術者、時間枠、または配車の制約を構造化された形式で要求する必要があります。ファンクションコーリングによるスケジューリングは、モデルが汎用APIの周囲で独自のワークフローを作り出すのではなく、正確なアクションを選択する時に最も機能します。

外部のエコシステムも実装の姿勢に影響を与えました。AnthropicのニュースやClaudeドキュメントは、いずれも同じプロダクトの課題を裏付けています。ユーザーはアシスタントが実際のツールに連携されることを期待していますが、運用チームはそのツールを監査可能で、制限され、復元可能な状態に保たなければなりません。

ユーザー体験

ユーザーがMCPサーバーを「インフラストラクチャ」として意識する必要はありません。明確な接続手順を経て、すでに選択して利用しているアシスタント内で便利な機能が使える体験であるべきです。理想的なフローはシンプルです。Crisphiveアカウントを接続し、アクセスを承認して、アシスタントにフィールドオペレーション業務のサポートを依頼するだけです。

一度連携されれば、アシスタントは現場の言葉で作業を提示できます。案件、技術者、スケジュール、配車時間枠、顧客への約束などです。ここで小規模事業者向けのMCP OAuthが意味を持ちます。小規模なチームはプロトコルの設定トラブルに対応したいわけではありません。連携されたアシスタントがプロダクトの他の部分と同じアカウント境界内で動作しているという安心感を求めているのです。

ユーザー体験の良し悪しは「抑制」にも依存します。アシスタントが文脈なしに利用可能なあらゆるツールを一覧表示してしまうと、機能は豊富に見えても扱いづらくなります。サーバーが明確に定義された限定的なアクションセットを提供していれば、アシスタントは重要な変更を加える前に不足している詳細を尋ねる確率が高まります。これが、単なる「項目チェックのためのMCP OAuth」と「日々の配車業務に耐えうる連携」との実質的な違いです。

MCPサーバーの実装例を比較している開発者への教訓は、ハンドシェイクだけでなく全体の経路を評価することです。優れているMCP OAuthの実装とは、認証、ディスカバリー、ツールの命名、およびエラーメッセージのすべてが、ユーザーを同じ安全な次のステップへと導いているものなのです。

得られた教訓

1つ目の教訓は、ディスカバリーはプロダクト開発そのものであるということです。.well-knownエンドポイントは一見すると単なる裏方の仕組みに見えますが、次に開発を行うエンジニアやクライアント、アシスタントが暗黙の了解なしに連携を理解できるかどうかを左右します。メタデータが明確であれば接続は意図したものになりますが、内容が薄いとクライアントごとに独自に補填せざるを得なくなります。

2つ目の教訓は、ツールスキーマには公開APIルートと同等の配慮が必要だということです。名前、説明、必須フィールド、検証メッセージのすべてが、モデルの動作環境の一部となります。「スケジュールを更新する」という表現は広すぎます。「技術者の稼働状況を確認した上で、提案された時間枠に案件を移動する」とする方が、ユーザーが実際に期待している作業に近くなります。

3つ目の教訓は、ガードレールはモデルよりも下の層に配置すべきだということです。アシスタントは丁寧にリクエストを発行できますが、制限を適用するのはサーバー側の役割です。これにはテナントチェック、権限チェック、引数の検証、ログ記録、およびリクエストを完了できない場合の解除パスが含まれます。これらの対応こそが、実際にMCP OAuthを改善する方法となります。許可されたパスを有用にし、未許可のパスを明確にすることです。

また、検索キーワードをそのままプロダクトの説明文に流用しないことも学びました。「AIエージェント用ツールAPI」、「ファンクションコーリングによるスケジューリング」、「MCPサーバーの実装例」といった用語は検索用の表現としては有用ですが、記事やプロダクト内では具象的なフィールドオペレーションの言葉で語る必要があります。そうでなければ、配車担当者のためではなくベンチマークテスト用に構築された連携のように見えてしまいます。

今後の展望

今後の取り組みは、サーバーの規模を拡大することよりも、機能をより明確にすることに重点を置きます。ツールの数を増やすことが役立つのは、それぞれのツールが明確な権限境界を持つ実際のフィールドオペレーションのアクションに対応している場合のみです。デモでは魅力的だが実稼働では曖昧に思える広範な機能を公開するよりも、信頼性の高いスケジューリングおよび配車ツールを限定して追加していく方針をとっています。

また、接続体験の継続的な向上も目指しています。2026年におけるMCP OAuthの価値は、安全に接続するためにユーザーに必要なプロトコル知識がどれだけ少なくて済むかによって評価されるようになるでしょう。開発者にとっては、ディスカバリーの向上、セットアップメッセージの明確化、そしてクライアント、認可サーバー、MCPのインターフェース間における隠れた前提条件の削減を意味します。

コンテンツやドキュメントについても同様です。「MCP OAuthのヒント」、「MCP OAuthの実装例」、「MCP OAuthのコスト」、「MCP OAuthの改善方法」といった検索は、いずれも同じニーズを示しています。開発者は実際のプロダクト運用に耐えうる実践的な情報を求めているのです。当社の回答は、認証パス、ディスカバリー規約、ツール設計、そして意図的に可視化しているエラーモードなど、検証されたシステムの構築要素を公開し続けることです。

ゴールは「アシスタントがAPIを呼び出せること」ではありません。アシスタントが可能な操作を理解し、ユーザーが承認した内容を把握し、リクエストが規約から外れた場合にはサーバーが適切に制限をかけるフィールドオペレーションのワークフローを確立することです。この取り組みは新機能のリリース発表ほど華やかではありませんが、単なるデモ用の画面と持続可能な運用パスを分ける重要な違いとなります。