API提供者のためのMCPサーバー設計ガイド / MCP Server Design Guide for API Providers

Presentation slides for CData MCP ナイト！
Session title: API提供者のためのMCPサーバー設計ガイド
Date: 2025/09/26

Transcript

1. All rights reserved by Postman Inc 川崎庸市 テクノロジー・エバンジェリスト API提供者のための MCPサーバ設計ガイド CData MCPナイト！ 2025.09.26
2. テクノロジーエバンジェリスト Postman株式会社 川崎 庸市 / Yoichi Kawasaki @postman_japan @yokawasa
3. お話すること • はじめに • AIエージェントの行動モデルから探るAIにとって使いやすいデータとは？ • API提供者のためのMCPサーバー設計ガイド
4. はじめに @postman_japan
5. MCP Model Context Protocol) Anthropic社が開発したLLMが外部ツールとやり取りするための標準化されたプロトコル Tools Resources Prompts MCP Server MCP Client JSONRPC 2.0 モデルが実行する機能 /関数APIリクエスト、ファイル書き込み ) ユーザー向けの定義済みテンプレート (slashコマンド、Q&A モデルへの追加コンテキストのためのデータ File、DBレコード) Prompts, resources, toolsを利用 コンテキストと機能 Capabilities)を提供す るサービス 機能 Capabilities) MCP spec https://modelcontextprotocol.io/specification/20250618 双方向接続
6. Before MCP AIのデータソースとの連携において新しいものが増えるたびに独自のカスタム実装が必要となり、真に連 携したシステムの拡張が困難になっていた。この課題解決のためにMCPはつくられた As AI assistants gain mainstream adoption, the industry has invested heavily in model capabilities, achieving rapid advances in reasoning and quality. Yet even the most sophisticated models are constrained by their isolation from data—trapped behind information silos and legacy systems. Every new data source requires its own custom implementation, making truly connected systems difficult to scale. MCP addresses this challenge. It provides a universal, open standard for connecting AI systems with data sources, replacing fragmented integrations with a single protocol. Introducing the Model Context Protocol by anthropic https://www.anthropic.com/news/model-context-protocol ChatGPT Claude My Agent Calendar Service Database Service Email Service それぞれの連携がカスタム実装されていた
7. After MCP • LLMがさまざまな外部ツールと標準化されたプロトコルで連携できるようになった • MCPは外部ツールとのインタラクションを簡素化する、アダプターとして機能 ChatGPT Claude My Agent Calendar Service Database Service Email Service MCP server for Email MCP server for Database MCP server for Calendar 一度MCPサーバーを構築すれば、どこでも活用可能
8. MCPが提供する技術的・ビジネス的メリット • 外部ツールとのインタラクションの簡素化 - LLMと外部リソースやアプリとの統合が容易になる（アダプター） - 動的ツール選択＆呼び出しによりツール呼び出しロジックの簡素化 - コンテキストを保持したツール活用でマルチステップ・ワークフローの簡素化 • 標準化とエコシステム - ベンダーニュートラルで相互運用が楽になる - MCP準拠技術・サービスの公開・流通がしやすくなる MCPが提供する技術的・ビジネス的メリット
9. • MCPを通じてAPIエコシステムは新しい利用層AI に開かれ、拡大していく APIエコシステムの展望 • API提供者は、品質の高いAPIを提供する必要があると同時に、AIにとって使いや すく・理解しやすいMCPを提供する必要がある
10. AIエージェントの行動モデルから探る AIにとって扱いやすいデータとは？ @postman_japan
11. AIエージェントとLLMの関係 LLMが推論と判断を担い、AIエージェントがその判断を実行に移して目標を達成する LLM（頭脳） - 推論 - 計画立案 AIエージェント - LLMに問い合わせ - 外部ツール実行 - コンテキスト管理 インプット アウトプット
12. APIの使い方: 人間 vs. AIエージェント 人間は「何をしたいのか、どのAPIを使うか」が明確だが、AIは「目標とコンテキスト」から出発 目標とコンテキスト 何をすべきか思考 ツール選択と順序決定 動的にAPI呼び出し (目標) やりたいことが明確 どのAPIか分かっている API仕様書読んで、詳細決定 決められた順序でAPI呼び出し Reasoning 推論
13. AIエージェントの行動モデル 多くのAIエージェントの行動モデルはReAct的 • ユーザーの目標やプロンプトを受け取る • → 内部で思考プロセス Chain-of-Thought) を展開 • → 必要に応じてツール API、DB、検索など)を実行 • → 観察（Observation） • → 次のステップを決定 ReAct Reaction + Action) ReAct: SYNERGIZING REASONING AND ACTING IN LANGUAGE MODELS (Yao et al., 2022) https://arxiv.org/pdf/2210.03629 AIエージェントの行動モデルを助ける情報が大切 • 意味や目的が明確な情報 • 一貫性・予測可能性がある情報 ※ ReAct的とはあくまで行動と思考の対話ループを持つという意味で Start Thought Action Observati on End
14. Affordance (アフォーダンス) • UX・デザイン文脈で「ある物体がどのように使えるかを直感的に示す特性」として知られている。例：ボ タンは「押すもの」、椅子は「座るもの」 • LLMにとってAffordance力が高いとは、 意味や目的の理解のための明確な情報（ヒントや構造）が 含まれていること ⇒ 機械可読、自己記述的、セマンティックな情報 “Affordances provide strong clues to the operations of things. Plates are for pushing. Knobs are for turning. Slots are for inserting things into. Balls are for throwing or bouncing. When affordances are taken advantage of, the user knows what to do just by looking: no picture, label, or instruction needed.ˮ Affordanceが正しく活用されていれば、ユーザーは見るだけで何を すべきか分かる。図もラベルも説明書も不要 — Donald A. Norman, “The Design of Everyday Thingsˮ 1988 ※自己記述的 = Self-descriptive そのまま読んでわかる ※セマンティック = 意味や目的が明確
15. 推論コスト・トークン制限 • LLMの推論コスト、トークン制限を考えてデータを提供する必要がある • LLMの性能をより効果的に引き出すには、大量の生データをそのまま渡すのではなく、LLMが扱い やすいように集計・加工・構造化されたなデータを渡すのが効果的 LLMが苦手なデータ • 大量データ • ノイズの多いデータ • 一貫性のないデータ • 構造化されてないデータ 対策（集計・加工） • 絞り込み • ノイズ除去 • 構造化 • フォーマット変換 効果 • 応答速度向上 • 推論の精度向上 • コスト削減 Materialized Viewパターンは 有効なアプローチの１つ Materialized View pattern　 https://learn.microsoft.com/en-us/azure/arc hitecture/patterns/materialized-view
16. API提供者のための MCPサーバー設計ガイド @postman_japan
17. MCPサーバーの主要な考慮事項 • 抽象化の粒度 • 推論補完 • 推論コスト・トークン制限 • セキュリティ
18. MCPとAPIはレイヤーが異なる 項目 API MCP 役割 機能やデータへのイ ンターフェース AIがAPIなどを使うた めのアダプター 利用者 人間、アプリ AI • APIはシステムとデータを外部と接続するコントラクト（契約）を持つインターフェース • 一方、MCPはAIによるAPIを含む外部ツール利用のための新しい手段 (アダプター) • 今後はAIからのAPIアクセスはMCP経由が主流になるでしょう • しかし、多くの業務処理やビジネスロジックはAPIを経由しなければ実行できない LLM API MCP 人間 App LLMは新しいAPIのClient と捉えることができる 今後AIAPIアクセスは MCP経由が主流に
19. リソース指向 REST) vs. 能力指向 MCP REST APIとMCPのインターフェースのあり方の違い（リソース vs. 能力、データ vs. 目的） リソース指向（REST API） 能力指向　MCP 目的 リソース・データの操作（CRUD） 目的の達成 → 能力・タスクの実行 表現形式 HTTPメソッド + パス GET /users/{id} ツール名 getUserProfile インターフェース粒度 リソース単位 (エンドポイント: user, product) 能力・タスク単位 (ツールとして定義: getUserProfile) 意味づけ方法 API仕様、APIドキュメント 自然言語でツールの意味・目的を説明 主な使い手 人間（＋今後はAI） AI
20. APIとMCPにおける抽象化の粒度の違い • APIとMCPは目的・設計指向が異なるため、適切な抽象化の粒度には違いがある ◦ API このリソース・データを操作したい ◦ MCP この目的を実現するためにこのタスク（能力）を実行したい https://x.com/yokawasa/status/1918200532424172021 クレームと返金処理の例: クレームで返金 API リソース・データ操作用のCRUD群 GET /claims/{id} POST /refunds PATCH /refunds/{id} GET /refunds/{id} MCP クレーム返金のためのタスク(能力) refundOrderForClaim(claim_id)
21. ツールの粒度調整 - 目的ベースの実用的なタスク単位 ツールをAIが実現したい目的ベースの実用的なタスク単位にする（≠ APIのCRUD群の粒度） • AIが目的達成のために必要な処理か？ • AIが少ない試行回数で目的を達成できるか？ クレームと返金処理の例: クレームで返金 API リソース・データ操作用のCRUD群 GET /claims/{id} POST /refunds PATCH /refunds/{id} GET /refunds/{id} MCP クレーム返金のためのタスク(能力) refundOrderForClaim(claim_id) GET /claims/{id} POST /refunds PATCH /refunds/{id} GET /refunds/{id} API MCP Server AI App refundOrderForClaim
22. MCPサーバーの自動生成ツール MCPサーバーのコード自動生成ツールはいろいろある • OpenAPI仕様を元に自動生成するアプローチが多い • PostmanはPostmanコレクション（公開限定）を元に MCPサーバーコードの自動生成ツールを公開 Postman MCPサーバーGenerator https://www.postman.com/explore/mcp-generator https://nordicapis.com/10-tools-for-building-mcp-servers/
23. APIからMCPの自動生成の落とし穴 APIとMCPには本質的なギャップがあるので、安易な自動生成は危険 • APIとMCPでは設計指向が異なる: リソース指向REST) vs. 能力指向MCP • APIの粒度でMCP化するといろいろ問題がある ◦ LLMはツールが多いのが苦手 ◦ LLMからの無駄なツール呼び出しが増える • 人が使う前提で記述されたAPIの説明はLLMには向いていないかもしれない ◦ 説明が曖昧だとLLMはハルシネーションを起こす可能性がある ◦ LLMは曖昧なツール名を判断できないかもしれない API MCP自動生成ツールを使うにしても、ボイラープレート的なものを生成している と認識し、その後のギャップを埋めるため補完対応が不可欠
24. 推論補完対策 - Affordance力の高いデータ提供 LLMが正しく推論を促すためのデータ提供が必要。 もし、提供するデータのAffordance力が低いとLLMはハルシネーションを起こすかもしれない • 不明瞭なツール説明:ツール名が曖昧だったり、各ツールの目的が明示的に説明されていないと、 LLM はどのツールをいつ使用するかを判断できない • 曖昧なパラメータ説明: パラメータの説明が曖昧だと、LLM が期待される形式や値を誤って判断し、 ツールの本来の目的について誤った想定をする可能性がある • 欠落したコンテキスト: 実際のレスポンス内容の例がないと、LLMは予想されるデータがどのように なるかを推測できず、ツールの動作について誤った仮定が生じる • 不十分なエラーガイダンス: エラーのドキュメントが不十分だと、LLM は次のアクションを判断でき ず、さらにハルシネーションが生じる可能性がある
25. 推論補完対策 - Affordance力の高いデータ提供 ツール名・説明、エラーメッセージなどを機械可読、自己記述的、セマンティックに Postman API MCPのget-tagged-entitiesツール情報 明確なツール名 ツールの意図や 詳細の説明 入力スキーマ： 型、範囲、制限、説明、 必須、など Annotations: ヒント＋追加メタ情報 Postman API MCPのget-collectionのエラー エラーの原因説明と対 策情報
26. 推論プロセスを補完するMCP機能 - Elicitation • MCPサーバーが実行時に動的にクライアント（LLM / ユーザー）から追加の情報や指示を収集する 機能。適切なコンテキストや意図を引き出すための仕組み • サーバーがクライアントを呼び出すという従来とは逆方向の通信なので注意が必要 ユースケース • Tool API呼び出し前に「本当に呼び出すべきか？」 の自己判断を支援 • Tool APIの前提条件 (フィルター条件、パラメータな ど) を自然言語で確保する導線として MCP elicitation https://modelcontextprotocol.io/specification/20250618/client/elicitation MCP 20250618仕様で導入 参考情報 Elicitationの現状 • 20250618導入仕様なのでまだ実運用例が少ない • まだまだ未サポートなクライアントが多い ◦ サポートクライアント : Postman、VS Codeなど サーバー起点の機能
27. 推論・トークンコスト対策 - ノイズの少ないデータ LLMの推論コスト・トークンコストを考慮し、不要なデータ・ノイズの多いデータを渡さない • LLMが迷わず正しく推論できるよう、必要なデータのみに絞る ◦ フィールド数・ツール呼び出し回数が多いと、推論・トークンコストが増大 ◦ まとめて必要な分だけ取る仕組みがあるとよい（GraphQLのようなイメージ） • 同じ意図・機能のツールを複数作らない ◦ get_user_info, fetch_user_profile, lookup_user どれもユーザー情報取得だけど名前・説明が微妙に違う ◦ LLMがどれを使えばよいか迷い、意図しない、無駄なTool Callを選択する ◦ affordance力が低い曖昧な名前・説明のツールセットも同様に無駄なTool Callの選択につながる ◦ GET /users API MCP Server AI App getUsers JSON Filtered JSON LLM どれを使えばいいのか？ • get_user_info • fetch_user_profile • lookup_user
28. 推論・トークンコスト対策 - ツール数 • ツール数とLLMパフォーマンス (プロンプト負荷など) の関係は定かではないが、ツールが多くなる と、LLMに認知負荷の増加、Affordance力の低いツールによるLLMの混乱が生ずる可能性が高く なるため、ツール数を増やしすぎないほうがよさそう • 2025/09時点でAIエージェントによってはMCP Tools数に制限がある GitHub Copilotのデフォルト 128ツール制限
29. ツール数を絞ったMCPサーバー例 - Postman MCPサーバー Postman 公式のリモートMCPサーバーはToolフルセットを返却するエンドポイント以外に、ミニマルな Toolを返却するエンドポイントを提供している Postman MCPサーバー https://t.ly/Vdymt PostmanリモートMCPサーバー • フルセット ◦ https://mcp.postman.com/mcp ◦ Tool数: 107 • ミニマル ◦ https://mcp.postman.com/minimal ◦ Tool数: 38 ＊ Tool数は 2025.09.26時点の数値
30. MCPサーバーを評価しよう モデルに何か依頼して、間違った情報が返されたり、間違ったツールを選択してほしくないですよね？ 作ったMCPサーバーの実装を定量的に評価しましょう • MCPは、LLMがアクションを要求し、結果を受け取るための標準的な仕組みなので、LLMがツールに適切にアクセスし、そ れを使用できることが大切 • MCP 実装の評価: LLMに提供されるツールが正しく、一貫して機能するか？ 評価ツール: mcp-evalsの評価プロセスとスコア例 1. MCPツールの評価シナリオを作成 2. シナリオをMCPサーバーに対して実行 3. LLMは、事前に定義された基準に基づいて回答を評価 4. 実装を改善のためのスコアとフィードバック取得 mcp-evals https://github.com/mclenhard/mcp-evals 5つの指標で5段階評価 正確性、完全性、関連性、明確性、推 論の健全性
31. セキュリティ対策 MCPにおける新たな脅威例 • ツールポイズニング：ツール説明の改ざんでAIを騙すリスク • データ漏洩：安全でないツール経由で機密情報流出の恐れ • Command & Control C2攻撃：MCP経由で隠れた通信チャネルの悪用 • アイデンティティ破壊：認証・認可の欠陥から不正アクセスリスク MCPサーバーを安全に運用するためのポイント • インフラ：安全なネットワークと必要な計算リソースの準備 • サーバーソフトウェア：MCP仕様に準拠した信頼できるソフトウェア実装、Rate-limitの実装 • ツール統合：外部ツール・内部システムとの安全な連携 • 認証・認可：クライアント認証＆ポリシーに基づくアクセス制御（MCPサーバー OAuth2.1実装の義務化） Enterprise-Grade Security for the Model Context Protocol MCP Frameworks and Mitigation Strategies • https://genai.owasp.org/2025/04/22/securing-ais-new-frontier-the-power-of-open-collaboration-on-mcp-security/ • https://arxiv.org/html/2504.08623v2
32. MCP 認可 仕様 MCP 20250618版でセキュリティ仕様が強化され、MCPサーバーをOAuthリソースサーバー（ OAuth 2.1 サポート）として明確に分類 MCP Authorization　 https://modelcontextprotocol.io/specification/20250618/basic/authorization • PKCE implementation MUST: All MCP clients must use Proof Key for Code Exchange PKCE) to prevent authorization code interception attacks. • Metadata discovery support SHOULD: MCP servers should support RFC8414 for automatic endpoint discovery. • Dynamic client registration SHOULD: MCP servers should support RFC7591 to enable seamless client onboarding. • Standardized error handling MUST: MCP servers must respond with specific HTTP status codes (401, 403, 400) for different authorization scenarios.
33. 主要OAuthプロバイダーの動的クライアント登録 DCRサポート 状況（2025/07時点） 参考情報 OAuthプロバイダー DCRサポート状況 Okta ◯ サポート(ref) Auth0 ◯ サポート (ref) Keycloak OSS ◯ サポート [ref] Microsoft Entra ID ❌ 未公式サポート・未確認 Amazon Cognito ❌ 未公式サポート・未確認
34. MCP認可20250618版)のフォローアップ記事 MCP認可フローを仕様から読み解く（ 20250618版） https://qiita.com/yokawasa/items/74717789465ef2aeedfe 参考情報
35. エンタープライズ導入で必要になってくる仕様 • 接続したいMCPサーバーごとに認証認可を繰り返さなければならな問題 — これを解決する仕様 SEP646 Enterprise-Managed Authorization Profile for MCP • MCP認可のIdPでの集中管理を実現 SEP646 Enterprise-Managed Authorization Profile for MCP https://github.com/modelcontextprotocol/modelcontextprotocol/pull/646 MCPの認証と認可の現在と未来 https://hi120ki.github.io/ja/blog/posts/20250728/
36. （おまけ）APIについて @postman_japan
37. ご参考: AI時代に求められるMCPとAPIの設計の話 https://speakerdeck.com/yokawasa/ai-ready-api-designing-mcp-and-apis-in-the-ai-era
38. AI時代の今もWeb APIはすべての基盤 人間とAIの両方が使える高品質なAPIが必要
39. Postmanは高品質なWeb APIの開発〜運用まで 単一ツールセットで支援できるAPIプラットフォーム • APIライフサイクルの管理 • APIガバナンスの策定・実施 • コラボレーションの促進 What is an API platform? https://www.postman.com/api-platform/ API利用者と提供者に対して次のことを支援：
40. APIプラットフォーム Postmanの API開発ライフサイクルにおける各ステージでの活用例 定義 設計 開発 テスト セキュリティ デプロイ 監視・観測 ビジネス システム Security ・・・ ドキュメント コード管理 システム設定 モック API Contracts (スキーマ) APIサーバー 開発 API Gateway 開発 トラフィック キャプチャ セキュリティ テスト 要件 Postman コレクション generate パフォーマンス テスト Contracts テスト E2E テスト ソースコード 成果物 commit 自動テスト APIサーバー Build/Deploy API Gateway Build/Deploy CI/CD ・・・ 配布 モニター アラート APM レポート APIカタログ API 開発ポータル trigger integration trigger ユーザー フィードバック Feedback loop UIテスト Stub generate @postman_japan
41. 多様なAPIアーキテクチャスタイルをサポート
42. MCP Model Context Protocol) リクエスト MCPサーバーの確認・デバッグのためのMCPクライアント STDIO、SSE、ストリーミング HTTPを介したMCP操作が可能 任意のMCPサーバに動作確認や デバッグができる MCP OAuth認可にも対応
43. AIリクエスト LLMモデルの評価) 任意のプロンプトとMCPツールでLLMモデルの評価
44. API 最新情報や Postman プラットフォームをもっと知りたい @postman_japan Postman API Night API 関連トークのミートアップ https://postman.connpass.com Postman Japan コミュニティ Discord https://discord.gg/G4SQWDDqVa Postman Qiita https://qiita.com/organizations/postmanjapan Postman Japan X https://x.com/postman_japan Postman Launchpad ランチタイムの Postman 最新情報 https://postman.connpass.com Postman オンライン ワークショップ 無料のハンズオン講習 https://postman.connpass.com
45. まとめ @postman_japan
46. まとめ • MCPの登場でLLMは様々な外部ツールと標準化されたプロトコルで連携できるようになった • APIエコシステムはMCPを通じ、AIという新しい利用層へ拡大する • API提供者は、高品質なAPIに加え、MCP対応が必要になっている • AIエージェントの行動モデルと扱いやすいデータ特性を理解しよう • AIの特性（抽象度、コスト、セキュリティなど）を考慮した、安全で使いやすいMCPサーバーを提供し よう
47. ご清聴いただき、ありがとうございました。 @postman_japan
48. OpenAPI 仕様 OAS OpenAPI （ 最新は2021年２月リリースの3.1）は、RESTful APIのためのAPI記述形式で、HTTP API機能を 人間とコンピュータが理解できるようにするためのプログラム言語に依存しない仕様形式 OpenAPI Specification 3.1 記述形式：JSON、YAML info メタデータ (バージョン、タイトル、ライセンス ) webhooks tags externalDocs servers APIサーバーURLや環境 security 認証認可 OAuth2, APIキー) paths APIエンドポイント、 HTTPメソッドなど定義 components 再利用可能なスキーマ、リクエスト・レスポンスモデルなど 参考情報
49. Postmanコレクション仕様 Postmanコレクションの記述形式。コレクションに含まれるAPIリクエストのAPIエンドポイント、リクエスト、 レスポンス、テストなどの情報やAPI 呼び出しのシーケンスを定義できます 記述形式：JSON Postman Collection v2.1 参考情報