mcp-builder

MCP サーバー開発ガイド

概要

LLM が適切に設計されたツールを通じて外部サービスとやり取りできる、MCP（Model Context Protocol）サーバーを作成します。MCP サーバーの品質は、LLM が実際のタスクをどれだけ適切に遂行できるかで測られます。

---

Microsoft MCP エコシステム

Microsoft は、Azure および Foundry サービス向けに広範な MCP インフラストラクチャを提供しています。このエコシステムを理解すると、カスタムサーバーを構築するか、既存のサーバーを活用するかを判断しやすくなります。

サーバーの種類

種類	トランスポート	用途	例
ローカル	stdio	デスクトップアプリ、単一ユーザー、ローカル開発	NPM/Docker 経由の Azure MCP Server
リモート	Streamable HTTP	クラウドサービス、マルチテナント、Agent Service	https://mcp.ai.azure.com（Foundry）

Microsoft MCP サーバー

カスタムサーバーを構築する前に、Microsoft がすでに提供しているものがないか確認してください。

サーバー	種類	説明
Azure MCP	ローカル	48 以上の Azure サービス（Storage、KeyVault、Cosmos、SQL など）
Foundry MCP	リモート	https://mcp.ai.azure.com - モデル、デプロイ、評価、エージェント
Fabric MCP	ローカル	Microsoft Fabric API、OneLake、アイテム定義
Playwright MCP	ローカル	ブラウザーの自動化とテスト
GitHub MCP	リモート	https://api.githubcopilot.com/mcp

エコシステム全体： サーバーの完全なカタログとパターンについては、🔷 Microsoft MCP Patterns を参照してください。

Microsoft のサーバーとカスタムサーバーの使い分け

シナリオ	推奨事項
Azure サービスとの連携	Azure MCP Server を使用します（48 サービスに対応）
AI Foundry のエージェント／評価	リモートサーバーの Foundry MCP を使用します
カスタムの社内 API	カスタムサーバー を構築します（このガイドを参照）
サードパーティの SaaS との連携	カスタムサーバー を構築します（このガイドを参照）
Azure MCP の拡張	Microsoft MCP Patterns に従います

---

プロセス

🚀 ワークフローの概要

高品質な MCP サーバーの作成には、主に 4 つのフェーズがあります。

フェーズ 1：綿密な調査と計画

1.1 最新の MCP 設計を理解する

API の網羅性とワークフローツール： API エンドポイントを幅広く網羅することと、特定のワークフロー向けツールとのバランスを取ります。ワークフローツールは特定のタスクでより便利な場合があり、幅広い網羅性があればエージェントは操作を柔軟に組み合わせられます。パフォーマンスはクライアントによって異なります。基本的なツールを組み合わせるコード実行が役立つクライアントもあれば、より高レベルのワークフローが適しているクライアントもあります。判断に迷う場合は、API の網羅性を優先してください。

ツールの命名と見つけやすさ： 明確で説明的なツール名を付けると、エージェントが適切なツールをすばやく見つけられます。一貫した接頭辞（例：github_create_issue、github_list_repos）を使い、アクションを表す名前にします。

コンテキスト管理： 簡潔なツールの説明と、結果をフィルタリングしたりページ分割したりする機能は、エージェントにとって有用です。焦点を絞った関連データを返すツールを設計してください。一部のクライアントではコード実行をサポートしており、エージェントが効率よくデータをフィルタリング、処理するのに役立ちます。

実用的なエラーメッセージ： エラーメッセージでは、具体的な提案と次の手順を示して、エージェントが解決策を見つけられるようにします。

1.2 MCP プロトコルのドキュメントを調べる

MCP 仕様を参照する：

サイトマップから関連ページを探します：https://modelcontextprotocol.io/sitemap.xml

次に、特定のページの URL に .md を付けて取得し、Markdown 形式で確認します（例：https://modelcontextprotocol.io/specification/draft.md）。

確認する主なページ：

• 仕様の概要とアーキテクチャ
• トランスポートの仕組み（Streamable HTTP、stdio）
• ツール、リソース、プロンプトの定義

1.3 フレームワークのドキュメントを確認する

言語の選択：

言語	最適な用途	SDK
TypeScript（推奨）	汎用的な MCP サーバー、幅広い互換性	@modelcontextprotocol/sdk
Python	データ／ML パイプライン、FastAPI との統合	mcp（FastMCP）
C#/.NET	Azure／Microsoft エコシステム、エンタープライズ	Microsoft.Mcp.Core

トランスポートの選択：

トランスポート	使用例	特徴
Streamable HTTP	リモートサーバー、マルチテナント、Agent Service	ステートレス、スケーラブル、認証が必要
stdio	ローカルサーバー、デスクトップアプリ	シンプル、シングルユーザー、ネットワーク不要

フレームワークのドキュメントを読み込む：

• MCP のベストプラクティス：📋 ベストプラクティスを見る - 基本的なガイドライン

TypeScript の場合（推奨）：

• TypeScript SDK：WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md を読み込みます
• ⚡ TypeScript ガイド - TypeScript のパターンと例

Python の場合：

• Python SDK：WebFetch を使用して https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md を読み込みます
• 🐍 Python ガイド - Python のパターンと例

C#/.NET の場合（Microsoft エコシステム）：

• 🔷 Microsoft MCP のパターン - C# のパターン、Azure MCP アーキテクチャ、コマンド階層

1.4 実装を計画する

API を理解する： サービスの API ドキュメントを確認し、主要なエンドポイント、認証要件、データモデルを特定します。必要に応じて Web 検索と WebFetch を使用します。

ツールの選択： 包括的な API カバレッジを優先します。実装するエンドポイントを、最も一般的な操作から順に列挙します。

---

フェーズ 2：実装

2.1 プロジェクト構成を設定する

プロジェクトの設定については、言語別のガイドを参照してください：

• ⚡ TypeScript ガイド - プロジェクト構成、package.json、tsconfig.json
• 🐍 Python ガイド - モジュール構成、依存関係
• 🔷 Microsoft MCP のパターン - C# のプロジェクト構成、コマンド階層

2.2 コアインフラストラクチャを実装する

共通ユーティリティを作成します：

• 認証機能を備えた API クライアント
• エラー処理ヘルパー
• レスポンスのフォーマット（JSON／Markdown）
• ページネーションのサポート

2.3 ツールを実装する

各ツールについて：

入力スキーマ：

• Zod（TypeScript）または Pydantic（Python）を使用します
• 制約と明確な説明を含めます
• フィールドの説明に例を追加します

出力スキーマ：

• 可能な場合は構造化データ用に outputSchema を定義します
• ツールのレスポンスで structuredContent を使用します（TypeScript SDK の機能）
• クライアントがツールの出力を理解して処理しやすくなります

ツールの説明：

• 機能の簡潔な概要
• パラメーターの説明
• 戻り値の型スキーマ

実装：

• I/O 操作には Async/await を使用します
• 対応方法がわかるメッセージを含む適切なエラー処理
• 該当する場合はページネーションをサポートします
• 最新の SDK を使用する場合は、テキストコンテンツと構造化データの両方を返します

アノテーション：

• readOnlyHint：true/false
• destructiveHint：true/false
• idempotentHint：true/false
• openWorldHint：true/false

---

フェーズ 3：レビューとテスト

3.1 コード品質

次の点を確認します：

• コードが重複していない（DRY の原則）
• エラー処理に一貫性がある
• 型が完全に指定されている
• ツールの説明が明確である

3.2 ビルドとテスト

TypeScript：

• npm run build を実行してコンパイルを確認します
• MCP Inspector でテストします：npx @modelcontextprotocol/inspector

Python：

• 構文を確認します：python -m py_compile your_server.py
• MCP Inspector でテストします

詳しいテスト方法と品質チェックリストについては、言語別のガイドを参照してください。

フェーズ 4：評価を作成する

MCP サーバーを実装したら、その有効性をテストするための包括的な評価を作成します。

完全な評価ガイドラインについては、✅ 評価ガイドを読み込んでください。

4.1 評価の目的を理解する

評価を使用して、LLM が MCP サーバーを効果的に利用し、現実的で複雑な質問に回答できるかをテストします。

4.2 評価用の質問を 10 個作成する

効果的な評価を作成するには、評価ガイドに記載された手順に従います。

1. ツールの調査：利用可能なツールを一覧表示し、その機能を理解します
2. コンテンツの探索：読み取り専用の操作を使用して、利用可能なデータを探索します
3. 質問の作成：複雑で現実的な質問を 10 個作成します
4. 回答の検証：各質問を自分で解いて、回答を検証します

4.3 評価の要件

各質問が以下の要件を満たすようにします。

• 独立している：他の質問に依存しません
• 読み取り専用である：非破壊的な操作のみが必要です
• 複雑である：複数のツール呼び出しと詳細な探索が必要です
• 現実的である：人々が関心を持つ実際のユースケースに基づいています
• 検証可能である：文字列比較で検証できる、明確で一意の回答があります
• 安定している：回答が時間の経過によって変わりません

4.4 出力形式

次の構造で XML ファイルを作成します。

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>

</evaluation>

---

参考ファイル

📚 ドキュメントライブラリ

開発中、必要に応じて以下のリソースを読み込みます。

MCP のコアドキュメント（最初に読み込む）

• MCP プロトコル：https://modelcontextprotocol.io/sitemap.xmlのサイトマップから始め、.mdサフィックスを付けて特定のページを取得します
• 📋 MCP のベストプラクティス - 以下を含む、あらゆる MCP に適用できるガイドライン：
  • サーバーとツールの命名規則
  • 応答形式のガイドライン（JSON と Markdown の比較）
  • ページネーションのベストプラクティス
  • トランスポートの選択（ストリーミング可能な HTTP と stdio の比較）
  • セキュリティとエラー処理の標準

Microsoft MCP ドキュメント（Azure／Foundry 用）

• 🔷 Microsoft MCP のパターン - 以下を含む、Microsoft 固有のパターン：
  • Azure MCP Server のアーキテクチャ（48 以上の Azure サービス）
  • C#/.NET コマンドの実装パターン
  • Foundry Agent Service を使用したリモート MCP
  • 認証（Entra ID、OBO フロー、マネージド ID）
  • Bicep テンプレートを使用したテストインフラストラクチャ

SDK ドキュメント（フェーズ 1／2 で読み込む）

• Python SDK：https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdから取得します
• TypeScript SDK：https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdから取得します
• Microsoft MCP SDK：C#/.NET については、Microsoft MCP のパターンを参照してください

言語別の実装ガイド（フェーズ 2 で読み込む）

• 🐍 Python 実装ガイド - 以下を含む、Python／FastMCP の完全ガイド：

  • サーバー初期化パターン
  • Pydantic モデルの例
  • @mcp.toolを使用したツールの登録
  • 完全に動作する例
  • 品質チェックリスト

• ⚡ TypeScript 実装ガイド - 以下を含む、TypeScript の完全ガイド：

  • プロジェクト構成
  • Zod スキーマのパターン
  • server.registerToolを使用したツールの登録
  • 完全に動作する例
  • 品質チェックリスト

• 🔷 Microsoft MCP のパターン - 以下を含む、C#/.NET の完全ガイド：

  • コマンド階層（BaseCommand → GlobalCommand → SubscriptionCommand）
  • 命名規則（{Resource}{Operation}Command）
  • .AsRequired()／.AsOptional()を使用したオプション処理
  • Azure Functions を使用したリモート MCP のデプロイ
  • Bicep を使用したライブテストのパターン

評価ガイド（フェーズ 4 で読み込む）

• ✅ 評価ガイド - 以下を含む、評価作成の完全ガイド：
  • 質問作成のガイドライン
  • 回答を検証する方法
  • XML 形式の仕様
  • 質問と回答の例
  • 提供されているスクリプトを使用した評価の実行