当社のMCPサーバーの構造：OAuth、.well-knownディスカバリ、そしてツール設計

MCP OAuthは、スケジューリングに関する会話を、それを承認する人物の権限へと結び付けます。50台以上の車両フリートを抱える配車システムの連携を構築する開発者にとって、最初の案件変更を行う前に、この権限の境界を整理しておくことが不可欠です。CrisphiveのMCPサーバーは、ディスカバリ、認可、指示決定ツールを単一の接続内にまとめます。接続のセットアップから実行に至るリクエストの流れを追い、クライアントが何をディスカバリし、誰の権限を受け取るのかを確認した上で、処理が成功した場合や停滞した場合に配車担当者にどう表示されるかを検証しましょう。

背景

予約業務の補助としてアシスタントを導入しようとしている、ある地域の配車チームを例に考えてみましょう。開発者は日常的な運用に耐えうる接続環境を望んでおり、配車担当者はアシスタントがどの事業体で作業しているのか、そして提案された変更が実際に反映されたのかを把握したいと考えています。開発者と配車マネージャーが一緒になって接続仕様を確認することが重要です。

Crisphive MCP サーバーのドキュメントでは、https://api.crisphive.com/mcp でホストされているリモートサーバーについて説明されています。これは公開デベロッパー API を Streamable HTTP 上のツールとして提供します。クライアントは OAuth 経由で接続するか、カスタム認可ヘッダーに対応している場合は API キーを使用できます。ドキュメントに記載されているスケジューリング経路は決定論的ソルバーを使用しており、会話を通じてそのスケジューリングシステムに対するツール呼び出しが行われます。

まずは、接続がアクセスすべき事業者と環境の確認から始めましょう。サンドボックスでの検証と、本番環境でのスケジューリング変更では、影響の大きさが全く異なります。クライアントに対し、受託事業者がどの環境をテストしているのか、誰がアクセスを承認するのか、そして引き渡し後に誰が接続を管理・所有するのかを明確にするよう求めてください。これらの回答はデプロイ設定のすぐ脇に記録し、次に担当する開発者が確認できるようにしておきます。

MCP サーバーのサンプルを参照する際は、認可の境界について説明されているものを選ぶようにしてください。接続が成功したという事実だけでは、オペレーターが正しいアクセス権限を持っていることの証明にはなりません。連携のプロトコル仕様については Model Context Protocol リファレンス を参照しつつ、実際のデプロイ時の動作についてはサーバーのドキュメントと照らし合わせて確認してください。

仕組み

接続処理はディスカバリから始まります。Crisphive のドキュメントでは、/.well-known/oauth-protected-resource に保護リソースドキュメント、/.well-known/oauth-authorization-server に認可サーバーのメタデータが定義されています。前者は認可サーバーを識別し、後者はクライアントに必要なエンドポイントを提供します。そのため、特にクライアントが一般的なエンドポイントではなく特定のツールプロファイルに接続する場合は、.well-known ディスカバリを検証可能な設定情報として扱ってください。

ドキュメントに沿ったフローは、動的クライアント登録、メンバーの認可、そしてトークン交換へと進みます。これには PKCE S256 が必須です。PKCE を使用することで、パブリッククライアントに共有シークレットを渡すことなく、認可フローを開始したクライアントにトークン交換を紐付けることができます。同意画面において事業者のメンバーが接続を承認すると、発行されるアクセス権限はそのメンバーのロールに従います（より限定的なスコープを要求することも可能です）。

どのメンバーが連携を承認すべきかを検討してください。実行する作業に見合う適切な権限を持った承認アカウントを選択します。まずワークフローに何が必要かを整理しましょう。ドキュメントに記載されている通り、トークンは承認したメンバーの事業者、リージョン、および環境に紐付けられます。クライアントが使用する予定のロールで、意図したアクセス権限が正しく機能するかテストしてください。

リフレッシュ処理については個別の検証が必要です。

サーバーはリフレッシュ時に更新されたトークンのペアを返します。他の処理が接続をリフレッシュしようとする前に、最新のペアを永続化してください。また、古いリフレッシュトークンを別のジョブで保持し続けることは避けてください。Crisphive の仕様では、重複リフレッシュに対する短い猶予期間が設けられており、置き換えられた古いトークンが後から再利用された場合は接続が失効されます。リトライを無害だと決めつけず、ドキュメントに示されたライフサイクルに基づいたリカバリ設計を行ってください。

次に、MCP ツールの設計によってスケジューリングリクエストが具体化されます。サーバーのドキュメントには、公開 API 仕様から生成されたツールについて説明されており、パス、クエリ、およびボディの各フィールドは単一の引数オブジェクトにフラット化されています。ファンクションコーリングによるスケジューリングを行う際は、引数を渡す前に実際のツールスキーマを精査してください。「AI エージェントツール API」というラベルだけでは、どのフィールドが案件を識別するのか、あるいはどの操作が変更を確定させるのかまでは分かりません。

ユーザーの体験

オペレーターはブラウザでアクセスを承認し、作業についての会話画面へと戻ります。画面上の説明は、どの案件か、どのクルーか、何が変更されたかといった、配車現場の言葉で記述してください。OAuth の専門用語は診断ログには役立ちますが、接続エラーが発生した際に配車マネージャーが受け取る唯一の説明であってはなりません。

緊急案件の割り込みを想定する場合、候補の検索、スケジュールの再調整案のプレビュー、そして変更の確定処理を明確に区別してください。Crisphive のドキュメントでは、これらはそれぞれ独立した操作として定義されています。構築するUI/UXでもこの区別を活かし、マネージャーが提案された変更内容を確認できるようにした上で、確定処理の前に承認手順を明確に提示してください。プレビューはあくまで提案段階に過ぎません。

中断が発生した場合の対策も講じておきます。

マネージャーが確認作業の途中で画面から離れることも考えられます。戻ってきた際に、直前のレスポンスで何が確定したのかを理解できる必要があります。変更リクエストを送信した後に連携が途切れた場合、表示された「成功しました」という断定的なテキストだけでは変更が成功した証拠にはなりません。リクエストを再試行する前に、オペレーターがスケジュールを確認し、結果が不確実な場合に管理者に報告できる仕組みを用意してください。

クライアントのセットアップにも明確な責任者が必要です。Claude との連携については、クライアント側の手順として Claude のドキュメント を参照してください。セットアップは個別に検証を行いましょう。製品のアップデート情報については Anthropic のニュースページ をご確認ください。新機能の発表記事は、実際のシステムで使用している接続設定の代わりにはなりません。

小規模事業者向けの MCP OAuth を検討している段階では、1人の承認メンバーから始めるかもしれません。しかし、複数拠点への展開にあたっては、各ワークフローに必要なアクセス権限を個別に確認する必要があります。会話内容と案件記録の不一致を調査する担当者も含め、実際の配車業務の責任者とともに MCP OAuth のサンプルを検証してください。

得られた知見

権限の境界をテストしましょう。「MCP OAuth ベストプラクティス」を検索しても、選択したロールが必要なスケジューリング作業を実行できるかどうかは分かりません。クライアント環境での MCP OAuth の改善策を決定するには、アクセス要件をテストケースに落とし込み、期待される結果を設定してください。意図通りアクセスが拒否されるケースも含めることで、チームが正しい制御を認識できるようになります。

開発チームと配車チームが共同で、以下のシナリオを検証してください。

• 想定しているメンバーのロールで接続し、利用可能なスケジューリング操作を確認する。
• 想定している権限を超える操作を要求し、オペレーターにどのように表示されるかを記録する。
• スケジューリングのリクエストを途中で中断し、再試行する前に結果を確認する手順を確立する。
• 接続をリフレッシュし、アプリケーションが新しいトークンペアを正しく保存することを確認する。

これらは提案される受入テストであり、実際の事故対応記録ではありません。テストの検証結果は連携設定とともに保管してください。そうすることで、将来の運用担当者が、当初の設計議論を再現することなく、サーバー側の保護機能なのか、あるいは開発会社がクライアント体験として組み込んだ確認手順なのかを区別できるようになります。

MCP OAuth ソフトウェアにおいて、サポートの責任体制は設定情報のすぐ近くで明確にすべきです。誰が接続を再認可できるのか？ 変更が反映されていない案件の調査は誰が行うのか？ 実用的な MCP OAuth のヒントは、責任者とリカバリルートを提示することでこれらの疑問に答えます。MCP OAuth のコストについての議論では、実装作業と継続的なサポート費用を分離して考えてください。認可プロトコルそれ自体がプロジェクトの価格を決定するわけではありません。

Crisphive が基盤となるエンジンを提供する一方で、開発パートナー企業はスケジューリングや配車ワークフローの構築に対して対価を得ることができます。Crisphive パートナープログラム では、利用可能なトラックや継続的なビジネスモデルについて説明しています。貴社の提供範囲やサポート責任に合ったトラックを選択してください。その事業性を、特定のフリートがどれだけの時間を削減できるかといった主張とは分けて考えてください。

次のステップ

MCP OAuth 2026 の導入に向けた検証を行うにあたり、配車チームが最初から最後までの流れを説明できるサンドボックス上のワークフローを選択してください。想定されるロールで接続し、ディスカバリを確認した上で、1つのリクエストが該当するツールをどのように通過するか追跡します。期待される結果と実際の結果を並べて検証し、相違がある場合は、アクセス権限を拡大する前にその原因を調査してください。

共有する検証記録には、メンバーのロールと環境を明記し、提案されたスケジューリング変更が確定されるポイントを記述してください。また、通信中断や接続期限切れの後にチームがテストしたリカバリ手順を追加します。サポート問い合わせを受ける担当者が、元の開発者を探すことなく調査を行えるだけの十分な詳細情報を残しておきましょう。

受託開発会社が連携システムを引き渡す前に、受入テストに配車マネージャーを同席させてください。マネージャーにワークフローを実行してもらい、最後のレスポンスが不確実な場合にどのような対応をとるかを説明してもらいます。少しでも躊躇したからといってすぐに手を貸すのではなく、どこで手が止まり、どこで開発者に助けを求めるかを観察します。該当のステップを修正してテストを繰り返し、その結果をもって、このワークフローを本番運用に移行できるかどうかを判断してください。