MCPサーバー設計 ​

MCPサーバーは、大規模言語モデル（LLM）がシステム内のデータにアクセスし、アクションを実行できるようにするツールの集合です。 MCPサーバー設計とは、AIエージェントがアプリケーションとやり取りするためのMCPを計画し、構造化するプロセスです。

MCPサーバーと従来のAPI ​

MCPサーバーと従来のAPIの違いを理解すると、効果的なMCPサーバーを設計するのに役立ちます。 従来のAPIは、ドキュメントを読み、意図的に選択し、レスポンスを処理するコードを記述する人間の開発者向けに構築されています。 MCPサーバーは、記述された説明からサーバーで実行できることを検出し、ロジックではなく推論によってそれらの説明に基づいて動作するLLM向けに構築されています。

APIは、細かいパラメーターと柔軟な操作に適しています。 MCPサーバーは、明確な説明、一貫した動作、焦点を絞ったツールに適しています。

MCPサーバー設計のベストプラクティス ​

Workatoは、MCPサーバー設計について次のベストプラクティスを推奨しています。

戦略的設計:

• 完全性よりも明確さ: 網羅的な詳細を含めるのではなく、サーバーを理解しやすくします。
• 利便性よりも一貫性: 利便性のためのグループ化ではなく、論理的なカテゴリで機能をグループ化します。
• 推論よりも明示性: すべての動作を明示的に定義します。
• 巧妙さよりも決定性: 一貫性があり予測可能な動作は、適応型ロジックよりもLLMが解釈しやすくなります。 コンテキストに関係なく、毎回同じように動作するツールを構築します。
• 失敗を通常のこととして扱う: 問題が発生したときにLLMが適切に回復できるよう、十分に具体的なエラーを返します。

LLMの推論を考慮した設計:

• LLMが正しいツールを選択できるように、詳細な説明を記述します
• エラーコードではなく、セマンティックな結果を使用します
• ページネーション、依存関係、制限を明示的に定義します
• MCPサーバーに狭く一貫性のあるスコープを提供します

実行可能にする:

• 3～5個のコアツールから開始します
• MCPサーバーを5～8個のツールに制限します
• 関連しないドメインを組み合わせないでください
• 実際のユーザーリクエストでテストします
• ツール選択の精度に基づいて反復します

MCPサーバーのスコープを定義する ​

MCPサーバーのスコープを定義するとは、どの機能を1つのサーバーにまとめるかを決定することです。 適切にスコープ設定されたサーバーは、特定の機能ドメインに対応し、関連するオブジェクトを操作し、意味のある作業単位を完了します。 スコープ設定が不適切なサーバーは、LLMが解釈しにくく、継続的な調整が必要になる可能性が高くなります。

構築前に、次の手順を使用してスコープを定義します。

• サーバーに含めるものを特定する: 機能ドメインを共有し、関連するオブジェクトを操作し、同様の権限を必要とする機能をグループ化します。 利便性のために関連しない機能を追加したり、異なる認証を必要とする操作を組み合わせたりしないでください。

• サーバータイプを選択する: MCPサーバーは通常、次の3つのカテゴリのいずれかに分類されます。

  • ベースサーバー: 顧客データ管理など、CRUD、クエリ、ルックアップのようなコア操作を処理します。
  • プロセスサーバー: 注文処理などの複数ステップのワークフローをOrchestrateします。
  • データサーバー: セールスパイプライン分析など、分析とレポート作成をサポートします。

• スコープを検証する: MCPサーバーが次のテストに合格することを確認します。

  • エレベーターピッチ: MCPサーバーの目的を1文で説明できますか。 簡潔な説明を提供できない場合、スコープが広すぎる可能性があります。
  • LLMの推論: LLMは名前だけでこのMCPサーバーをいつ使用すべきか推論できますか。 詳細な説明が必要な場合は、スコープを簡素化します。
  • 完全性: 3～5個の主要なユースケースを、このサーバーだけで完了できますか。 ほとんどのワークフローで複数のサーバーが必要な場合、スコープが狭すぎる可能性があります。

• ツール数をシグナルとして使用する: MCPサーバーごとに5～8個のツールを使用します。 8～12個のツールは妥当です。 15個を超えるツールがある場合は、MCPサーバーを別々のドメインに分割することを検討してください。

一般的なスコープの誤りを避けるために、次の表を参考にしてください。

MCPサーバーのスコープを計画する ​

MCPサーバーのスコープを計画するときは、次の原則を検討してください。

• MCPサーバーの目的を特定
• MCPサーバーのタイプを選択

MCPサーバーの目的を特定する ​

MCPサーバーには、特定の機能ドメインに対応し、関連するオブジェクトを操作し、同様の権限を共有し、意味のある作業単位を完了する機能を含める必要があります。 利便性のための関連しない機能、異なる認証を必要とする操作、概念的な境界を曖昧にする機能は含めないでください。

MCPサーバータイプを選択する ​

ユースケースに必要なMCPサーバーのタイプを決定します。

• ベースサーバー: コア操作

  • 用途: CRUD操作、クエリ、ルックアップ
  • 例: 顧客データ管理

• プロセスサーバー: ワークフローのオーケストレーション

  • 用途: 複数ステップのビジネスプロセス
  • 例: 注文処理ワークフロー

• データサーバー: 分析とInsights

  • 用途: 集計、レポート、分析
  • 例: セールスパイプライン分析

MCPサーバー説明 ​

MCPサーバーを接続すると、MCPサーバーの説明がLLMと自動的に共有されます。 特定のユースケースに合わせて、また実行するツールのカスタマイズを含めるために、説明を更新できます。 正確なMCPサーバーの説明は、特定のツールを使用するタイミングをLLMが把握するのに役立ちます。

効果的なMCPサーバー説明を記述するには、次のガイドラインを使用します。

詳細なMCPサーバー説明を記述する ​

次の情報を含む詳細なMCPサーバー説明を提供します。

• 主要ドメイン
• 処理される主なオブジェクト
• コア操作
• 明示的な除外事項

✅推奨-定義されたドメインと操作、オブジェクト処理、明示的な除外を使用します。 例:

Manages sales opportunities, accounts, and contacts within a CRM system.
Provides tools to search, create, update, and analyze sales data, including
pipeline tracking and deal reporting. Does not handle customer support
tickets, marketing campaigns, or administrative configuration.

❌非推奨-複数のドメインと広範な操作を含む包括的なMCP。 例:

Manages sales opportunities, accounts, and contacts.
Provides tools to search, create, update, and analyze sales data, including
pipeline tracking and deal reporting. Provides tools to process customer support
tickets, manage marketing campaigns, and configure administrative settings, including customer visibility, team member visibility, and custom branding.

MCPサーバーの入力と出力を定義する ​

明確な入力処理と出力構造を定義すると、LLMが使用するツールを特定し、入力を検証し、正しい出力を提供するのに役立ちます。

入力処理 ​

入力を明示的に検証する指示を提供します。 例:

✅推奨-明示的な検証

def create_customer(name: str, email: Optional[str] = None):
    if not name:
        return {"error": "Name is required"}
    if email and not is_valid_email(email):
        return {"error": "Invalid email format"}
    # Proceed with creation

❌非推奨-暗黙的なデフォルト

def create_customer(name: str = "", email: str = "[email protected]"):
    # Creates customer with placeholder values

LLMが任意フィールドを正しく処理できるように、詳細な情報を提供します。 例:

✅推奨-スキップセマンティクス

def update_customer(id: str, **fields):
    updates = {}
    if "email" in fields:
        updates["email"] = fields["email"]
    if "phone" in fields:
        updates["phone"] = fields["phone"]
    # Only update explicitly provided fields

❌非推奨-任意フィールドの暗黙的なデフォルト。

def update_customer(id: str, email: str = None, phone: str = None):
    # Always updates email and phone, even when not intended

出力構造 ​

出力構造でページネーションを明示的に定義します。 例:

✅推奨-明確な切り捨てシグナル

{
  "results": [...],
  "has_more": true,
  "cursor": "eyJwYWdlIjogMn0="
}

❌非推奨-サイレントな切り捨て。

{
  "results": [...]
}

出力構造には一貫したフィールド名を使用してください。 例:

✅推奨-一貫した規則を使用

// All tools use same field names
{"customer_id": "90876", "email_address": "[email protected]"}

❌非推奨-一貫性のない命名

// Different tools use different names
{"customerId": "90876", "email": "[email protected]"}
{"customer_id": "45674", "user_email": "[email protected]"}

エラー処理 ​

MCPサーバーのセマンティックエラーを定義してください。 これにより、ユーザーとLLMは何が問題だったかを理解できます。 例:

✅推奨-セマンティックな意味

{
  "error": "No customers found matching 'Acme Corp'",
  "error_type": "not_found",
  "retry": false
}

❌非推奨-技術コード

{
  "error_code": 404,
  "message": "ERR_NOT_FOUND"
}

LLMがエラーの処理方法を理解できるように、エラーを一貫してマッピングしてください。 例:

必須フィールドの規則を適用する ​

MCPサーバー内の各ツールに必須フィールドの規則を適用してください。

• 一貫した大文字と小文字を使用する: 基盤となるAPIスタイルに合わせます
• エラーフィールドの命名: 小文字のerrorフィールドを使用します
• ページネーションフラグ:
  • has_more: 標準ページネーション用
  • has_more_chunks: ストリーミングレスポンス用
  • 1つのサーバー内でスタイルを混在させないでください

効果的なMCPサーバーツールを設計する ​

特定のツールユースケースを中心にMCPサーバーを設計します。 有効にする予定のワークフローから開始し、必要なツール、各ツールが返すデータ、ツール間のやり取りを決定します。 各コンポーネントは相互に関連しており、これらの関係を理解することで、効率的で信頼性が高く、構成可能なMCPサーバーを設計できます。 データ戦略や開発者エクスペリエンスの考慮事項を含む、包括的なMCPサーバーツール設計の原則については、MCPサーバーツール設計を参照してください。

MCPサーバーには通常、次のコンポーネントが含まれます。

• ツール: AIエージェントが実行できるアクション（スキル）を定義します。
• ツールアーキテクチャ: ツールの構造、および他のツールやアプリとのやり取りの方法を指定します。
• データ戦略: AIエージェントに返される情報を制御します。
• ツール説明: AIエージェントが各ツールを理解して使用する方法を決定します。

MCPサーバーをテストする ​

ツールが正確に選択されることを確認するために、MCPサーバーをテストします。 例:

複数ターンの会話におけるLLMレスポンスをテストします。 例:

Turn 1: "Find customers"
→ LLM should ask for search criteria

Turn 2: "All customers in California"
→ LLM should use the previous context + the new filter to provide a list of customers in California

Turn 3: "Show me the first one"
→ LLM should provide the first customer from the California results

構成可能性を確保するために、複数ツールのワークフローをテストします。 例:

1. search_products(query="laptop") → returns product IDs
2. get_product_details(id="45678") → returns full info
3. check_inventory(id="90876") → returns availability

さまざまなシナリオでMCPサーバーがどのように動作するかを理解するために、エッジケースもテストする必要があります。 例:

PRD作成とツール検証のユースケース例 ​

次のユースケース例では、製品要求ドキュメント（PRD）を作成および検証するためのツールを公開するMCPサーバーで作業するときに、テストプロセスを適用する方法の概要を示します。

プロダクトマネージャーは、新機能のために構造化されたPRDを作成する必要があります。 MCPサーバーは、PRDを定義、保存、取得するためのツールを提供します。 各ツールは文書化された契約に照らして検証する必要があり、PRD内の各ユースケースはPRDが公開される前に構造化されたアーティファクトを使用してテストする必要があります。 PRD主導のテストプロセスにより、すべてのツールが予測どおりに動作し、入力と出力がPRDの定義済み要件と一致し、ツールまたはその説明に対する将来の変更を検証できるようになります。

プロセスは、目標、入力、期待される出力、合格/不合格基準など、各PRDセクションを特定のツール呼び出しにマッピングすることから始まります。 その後、テストアーティファクトが記録される前に、各ツールが契約に照らして検証されます。 ツールの動作とルーティングが一貫したままであることを確認するために、変更後には回帰テストを実行する必要があります。

ワークフローの概要

• PRDユースケースを定義する: プロダクトマネージャーは機能を特定し、create_prdツールを使用して目標、入力、期待される出力、合格/不合格基準を文書化します。
• ツール契約を検証する: create_prd、get_prd、update_prdなどの各ツールに、1行の目的、必須および任意のパラメーター、期待されるレスポンス形式、エラー動作があることを確認します。
• テストアーティファクトを記録する: チームはrecord_testツールを使用して、各ツール呼び出しの構造化されたアーティファクトをログに記録し、入力、期待される出力、実際の結果、合格/不合格ステータスを取得します。
• PRDセクションを検証する: 目標、入力、期待される出力、合格/不合格基準など、PRDの各セクションは、出力が定義済み要件と一致することを確認するために、ツールのレスポンスに照らして検証されます。
• 回帰テスト（任意）：ツールの説明またはパラメーターへの変更、および影響を受けるテスト成果物をテストします。 複数ツールのワークフローを検証し、意図しない副作用がないか確認します。

次の図は、このワークフローを示しています。