mcp-server-design

MCP サーバーの設計

概要

このスキルでは、LLM エージェントと効果的に連携する MCP（Model Context Protocol）サーバーを設計するためのベストプラクティスを紹介します。重要なポイントは、自動化ではなくエージェント向けに設計することです。LLM は API の利用者ではなく、人間のように考える存在です。

基本理念

自動化ではなく、エージェント向けに設計する

従来の API 設計では、きめ細かなエンドポイントによるプログラムからのアクセスを最適化します。MCP ツールの設計では、LLM の思考や推論の方法に合わせて最適化する必要があります。

• LLM は人間のように考えます：意図、コンテキスト、目的を理解します
• ツールはエンドポイントではなくタスクにします：ユーザーが達成したいことを中心にツールを設計します
• 認知負荷を減らします：目的が明確な少数のツールは、細分化された多数のツールに勝ります

3 つの柱

1. すべてをすぐに使える状態で提供します：完全で、実行に移せる情報を提供します
2. 労力を減らします：タスクの達成に必要な手順を最小限にします
3. 選択肢を減らします：LLM が判断する必要のある分岐を限定します

ツール設計の原則

1. 汎用ラッパーより、目的に特化したツールを優先する

アンチパターン：すべての API エンドポイントをツールとしてラップする

// Bad: Generic database tools
// src/tools/run-sql.ts
// src/tools/list-tables.ts
// src/tools/describe-table.ts

ベストプラクティス：ユーザーのタスクを中心にツールを設計する

// Good: Task-oriented tools
// src/tools/prepare-database-migration.ts
import { z } from "zod";
import type { ToolMetadata } from "xmcp";

export const schema = {
  description: z.string().describe("What database changes are needed"),
};

export const metadata: ToolMetadata = {
  name: "prepare-database-migration",
  description: "Design a database change with safety checks and reviewed migration plan",
};

// src/tools/analyze-slow-queries.ts
// src/tools/create-backup.ts

2. ツールの数を最小限にする

LLM は長いツール一覧の扱いに苦労します。ツールを追加するたびに、次のような影響があります。

• 選択時の混乱が増える
• すべてのリクエストにトークンが追加される
• 各ツールの目的が曖昧になる

ガイドライン：

• まず、核となるツールを 5～10 個用意します
• 評価によって必要性が示された場合にのみ、ツールを追加します
• 適切な場合は、関連する操作を統合します

3. 実装方法ではなく、目的に基づいてツールに名前を付ける

ツール名は LLM の動作を導きます。名前では仕組みではなく、タスクを説明します。

代わりに...	次を使用...
post-slack-message	notify-team
run-sql-query	analyze-data
call-api-endpoint	check-service-status

4. タスクの形に合わせてツールを設計する

複雑なフローでは、ステップごとに 1 つのツールを用意するより、タスクごとに 1 つのツールを用意するほうが効果的です。

アンチパターン：デプロイを個別の操作に分割する

// Bad: Too many granular tools
// src/tools/create-branch.ts
// src/tools/commit-changes.ts
// src/tools/push-branch.ts
// src/tools/create-pr.ts
// src/tools/run-tests.ts
// src/tools/merge-pr.ts

ベストプラクティス：タスク全体を実行する単一のツールを用意する

// src/tools/deploy-changes.ts
import { z } from "zod";
import type { ToolMetadata } from "xmcp";

export const schema = {
  description: z.string().describe("What changes are being deployed"),
  runTests: z.boolean().default(true).describe("Run test suite first"),
  autoMerge: z.boolean().default(false).describe("Auto-merge after tests pass"),
};

export const metadata: ToolMetadata = {
  name: "deploy-changes",
  description: "Deploy current changes through the complete workflow",
};

export default function deployChanges({ description, runTests, autoMerge }) {
  // Handles: branch creation, commit, push, PR, tests, merge
}

判断の枠組み

新しいツールを作成するタイミング

次の場合に、新しいツールを作成します。

• ユーザーがこの機能を頻繁に求める
• タスクの範囲と目的が明確である
• 既存のツールでは適切に実行できない
• 評価で、LLM がこのタスクに不適切なツールを選択すると分かった

次の場合は、新しいツールを作成しないでください。

• 既存のツールでパラメーターを少し変えるだけで対応できる
• 機能が重複する（代わりに統合します）
• まれなエッジケースである（既存のツールとガイダンスで対応します）

操作を統合するタイミング

次の場合は、複数の操作を 1 つのツールに統合します。

• ほとんどの場合、それらの操作が一緒に使われる
• 中間結果に単独での有用性がない
• 分割すると不要な判断ポイントが生まれる

次の場合は、操作を分けておきます。

• ユーザーに細かな制御が必要である
• 中間結果に単独での価値がある
• 統合するとツールが複雑になりすぎる

粒度のバランスを取る

粒度の細かいツール	統合されたツール
柔軟性が高い	メンタルモデルがシンプル
選択の負担が大きい	意図が明確
誤用のリスクがある	カスタマイズ性が低い

クイックリファレンス

ツール設計チェックリスト

• 実装方法ではなく、目的に基づいた名前になっている
• 説明に、使用するタイミングが記載されている
• パラメーターの説明が明確である
• 応答に次のステップやコンテキストが含まれている
• 実際の LLM リクエストでテストされている

注意すべき兆候

• 単一のサーバーに 15 個を超えるツールがある
• HTTP メソッドやエンドポイントにちなんだ名前のツールがある
• 「何でもできる」汎用ツールがある
• 1 つのタスクに複数回の呼び出しが必要なツールがある

リソース

references/

• design-principles.md - 詳細な例、アンチパターン、実際の事例

これらの概念をさらに詳しく知るには、設計原則のリファレンスドキュメントをお読みください。