【2026年】MCPサーバー開発チュートリアル2026｜Model Context Protocol完全ガイド

SDK の選び方：Python と TypeScript の特徴と SDK 比較表

MCP サーバー開発において使用する言語やフレームワークは、開発者のバックグラウンドや既存のインフラに依存しますが、公式にサポートされている主要な SDK は Python (mcp) と TypeScript (@modelcontextprotocol/sdk) の二つです。Python を選択する場合、データの処理や分析との親和性が高く、データサイエンティストや AI 研究者にとって馴染み深い環境と言えます。2026 年現在では mcp ライブラリのバージョン 1.2.x が安定版として提供されており、非同期通信 (async/await) の完全なサポートや、Pydantic を用いたスキーマ検証の充実が特徴です。

対照的に、TypeScript 版の SDK は Web エコシステムとの統合に強みを持っています。Node.js ベースで動作するため、既存の Web サーバー（Express や Fastify）と組み合わせてハイブリッドな MCP サーバーを構築するのが容易です。また、ブラウザ上で直接動作させる場合や、JavaScript/TypeScript で書かれたミドルウェアを経由して通信を行う必要のあるケースでは TypeScript SDK が最適解となります。両者の間には機能差はほとんどありませんが、エコシステムや開発チームのスキルセットに合わせて選択することが成功への鍵となります。

比較すると、Python はデータ処理ライブラリ（Pandas や NumPy）との連携が容易で、複雑な計算を含むツール実装に適しています。一方、TypeScript はフロントエンド技術者にとって学習コストが低く、リアルタイム通信やストリーミング処理の実装が直感的です。また、型安全性の観点からも TypeScript の方が優れており、大規模な MCP サーバーを構築する際の保守性を高めるのに役立ちます。プロジェクトの要件に応じて、あるいはチームの既存資産に基づいて最適な SDK を選定してください。

Python による MCP サーバー開発実践（ファイルシステム連携）

具体的な実装例として、Python を用いたファイルシステムアクセス機能を持つ MCP サーバーの作成手順を解説します。まず、仮想環境を構築し、必要なパッケージをインストールすることから始めます。pip install mcp pydantic requests といったコマンドで依存関係を解決しますが、2026 年時点では mcp ライブラリ自体が多くの機能を内包しているため、追加の依存関係は最小限に抑えられています。環境構築が終わったら、サーバーロジックを記述する主ファイルを作成します。この際、Python の非同期機能である async/await を活用して、I/O 待ち時間を最小化することが重要です。

基本的なサーバー構造では、mcp.Server クラスをインスタンス化し、リソース定義やツール定義を登録します。例えば、ファイルシステムにアクセスするためのツールを実装する場合、read_file や write_file のような関数を定義し、それぞれの引数と戻り値の型情報を Pydantic モデルで厳密に定義します。これにより、入力されたパラメータが不正な場合や、権限がない場合に即座にエラーを返すことができます。また、ファイルパスの相対指定や絶対指定を統一し、セキュリティホールとならないよう事前検証を行うロジックを含める必要があります。

実装例における重要なポイントは、エラーハンドリングと例外処理です。外部ファイルシステムへのアクセスは、権限不足や存在しないファイルなど、予期せぬエラーが発生しやすい領域です。Python の try-except ブロックを用いてこれらの例外をキャッチし、MCP プロトコル仕様に沿ったエラーレスポンスを返す処理を実装します。具体的には、エラーコードとメッセージを JSON-RPC エラー形式で整形して送出することで、クライアント側である Claude Desktop などの AI モデルが適切に状況を判断できるようになります。このように堅牢なエラー処理を組み込むことで、ユーザー体験を損なうことなく信頼性の高いツールを提供できます。

TypeScript による MCP サーバー開発実践（API 連携）

次に、TypeScript を用いた API 連携の実装例について解説します。Node.js 環境で動作する MCP サーバーを作成するには、npm init -y でプロジェクトを初期化し、@modelcontextprotocol/sdk と axios または node-fetch のような HTTP クライアントライブラリを導入します。TypeScript の場合、型定義ファイルが充実しているため、API エンドポイントのレスポンス構造をインターフェースとして事前に定義しておくと、開発中のミスを防げます。また、非同期処理については JavaScript の Promise ベースの記述法に慣れている必要があるため、async/await 文法を一貫して使用することを推奨します。

API 連携におけるセキュリティ対策は特に重要です。GitHub API や Notion API といった外部サービスを利用する際、認証トークンやシークレットキーをハードコードすることは絶対に避けるべきです。環境変数を用いて機密情報を管理し、起動時に読み込む仕組みを実装します。TypeScript の dotenv ライブラリを使用することで、ローカル開発環境でも安全な設定が可能になります。さらに、API リクエストを行う際にレート制限に抵触しないよう、適切な待機処理やリトライロジックを実装することが、2026 年の標準的な実装パターンとなっています。

リソース定義の側面でも、TypeScript の強みが発揮されます。例えば、データベース内のデータをリソースとして公開する場合、SQLite や [PostgreSQL を接続してクエリを実行するコードを記述します。この際、SQL インジェクションを防ぐためにパラメータ化されたクエリを使用し、また結果のサイズ制限を設けることで、メモリオーバーフローや応答遅延を防ぎます。TypeScript の型システムを活用してデータベースのスキーマと MCP サーバーのレスポンス構造を紐付けることで、型安全なデータ転送を実現できます。このように Web 技術との親和性を活かすことで、複雑なバックエンド連携もスムーズに行えます。

Claude Desktop との統合設定と claude_desktop_config.json の詳細

MCP サーバーの開発が完了したら、次は実際に AI クライアントである Claude Desktop と統合します。Claude Desktop は、Anthropic によって提供されるデスクトップアプリケーションであり、2026 年現在では MCP プロトコルをネイティブサポートしています。統合の手順としては、まず MCP サーバーの起動スクリプト（または実行バイナリ）を作成し、それを Claude Desktop の設定ファイルに指定する必要があります。この設定は claude_desktop_config.json ファイルで行われ、OS ごとにパスが異なるため注意が必要です。

設定ファイルの中身は JSON 形式で記述され、MCP サーバーの名前、コマンド、および起動引数を含みます。Windows の場合のパスには半角スラッシュ / またはバックスラッシュ \ の扱いに細心の注意が必要であり、MacOS や Linux では Unix 標準のパス指定を行います。例えば、Python で記述したサーバーを指定する場合は、Python インタープリタへのパスとスクリプトへのパスを明確に分けて記載します。また、環境変数が必要な場合は、設定ファイル内で env キーを使用して追加で定義することも可能です。

セキュリティ面では、Claude Desktop が実行するプロセスがユーザーの権限範囲を超えないように注意する必要があります。MCP サーバーは、通常はユーザーがログインしているアカウントの権限で動作しますが、必要に応じて特定のディレクトリへのアクセス制限を設けることが推奨されます。設定ファイルにはコメントも記述可能であるため、各サーバーの目的や権限範囲について注釈を残しておくことで、後日のメンテナンス性を向上させることができます。このように細部まで設定を見直すことで、安全かつ効率的な AI エージェント環境が整います。

セキュリティ対策：サンドボックス、権限管理、リスク回避

MCP サーバーを実装する上で最も重視すべき点の一つにセキュリティがあります。AI モデルは外部ツールを呼び出す際に、意図しない挙動や悪意あるプロンプトによる攻撃の対象となる可能性があります。そのため、サーバー側で厳格な権限管理とサンドボックス化の実施が必須です。具体的には、ファイルシステムアクセスを行う際、指定されたディレクトリ以外への書き込みを拒否する制限をかけます。また、データベース連携においては、読み取り専用アカウントを使用し、DROP TABLE などの破壊的な操作を実行できないよう制御します。

権限管理の手法としては、ロールベースアクセスコントロール（RBAC）を導入することが有効です。ユーザーごとに異なるレベルの権限を設定し、例えば「閲覧者」にはリソースの読み取りのみ許可する一方で、「管理者」にはツールの実行も許可するという区分けを行います。これにより、万が一 AI モデルが誤った判断を下したとしても、被害を最小限に抑えることが可能になります。さらに、2026 年時点では、コンテナ技術を用いて MCP サーバーを隔離して実行するアプローチも一般的になっており、サーバー側のリソース汚染を防ぐための標準的なプラクティスとして採用されています。

また、通信経路の暗号化も重要なセキュリティ要素です。HTTP トランスポートを使用する場合、必ず HTTPS 通信を強制し、中間者攻撃から保護します。また、認証トークンの保存場所についても、OS のキーチェーンやシークレットマネージャーを利用し、平文で保存しないようにします。これらの対策を講じることで、MCP サーバーが外部からの悪意あるアクセスに対して強靭な耐性を持つようになります。セキュリティは一度設定すれば終わりではなく、定期的な監査とパッチ適用を通じて維持していく必要があります。

デバッグと監視：MCP Inspector の活用とログ出力戦略

開発中の MCP サーバーを効果的にデバッグするためには、Anthropic が提供する公式ツール「MCP Inspector」が極めて有用です。このツールは、ローカルで動作する MCP サーバーのメッセージフローやステータスを可視化するためのインターフェースを提供します。起動方法はシンプルで、コマンドラインから npx @modelcontextprotocol/inspector を実行することで Web 画面が開きます。これにより、ホスト側からのリクエストとサーバー側のレスポンスをリアルタイムに確認でき、通信エラーやパラメータの不一致といった問題を手早く特定できます。

ログ出力については、開発段階では console.log を多用して詳細な情報を取得することが推奨されます。しかし、2026 年のベストプラクティスとしては、適切なロギングレベル（INFO, WARN, ERROR）を設定し、重要なイベントのみを記録する方が望ましいです。特にエラー発生時のスタックトレースを含めることで、問題の根本原因を特定しやすくなります。また、ログファイルのローテーション設定を行い、ディスク容量が枯渇しないように管理することも重要です。

監視とアラート機能も運用段階では必須となります。MCP サーバーがダウンした際や、応答遅延が発生した際に開発者に通知する仕組みを構築します。クラウド環境で動作させる場合は、CloudWatch や Datadog などのモニタリングサービスと連携し、リソースの使用状況を可視化します。これにより、ユーザーに不快感を与えずに高可用性な AI エージェント環境を提供できます。デバッグツールと監視体制を整えることで、開発から運用まで一貫した品質管理が可能です。

よくある質問（FAQ）

Q1. MCP サーバーのインストール時に依存関係のエラーが出ます

A. 依存関係エラーは Python バージョンや Node.js のバージョン不一致が原因であることが多いです。まずは mcp ライブラリが対応している最低要件を確認し、Python 3.10 以上や Node.js 18 以上を使用しているか再確認してください。仮想環境（venv）を作成してクリーンな状態でインストールすると解決することが多いため、それを利用することを強く推奨します。

Q2. Claude Desktop で MCP サーバーが認識されません

A. まず claude_desktop_config.json ファイルのパスが正しいか確認し、JSON 記法に誤りがないか検証してください。また、サーバー起動コマンドが実行可能権限を持っているかも確認します。エラーログを確認し、プロセスが正常に終了するか監視することも重要です。

Q3. TypeScript SDK と Python SDK のどちらを選ぶべきですか

A. データ処理や分析ツールを開発する場合は Python を、Web 統合やリアルタイム通信が必要な場合は TypeScript を選択するのが一般的です。既存のライブラリエコシステムやチームの技術スタックに合致している方を選びましょう。機能面での大きな差はありません。

Q4. MCP Inspector が起動しません

A. npx コマンドが正しく実行されているか確認し、npm のキャッシュをクリアしてみてください。また、バージョン 1.x の SDK を使用していることを前提としているため、古いバージョンのインストールが残っていないかチェックしてください。ブラウザのセキュリティ設定も影響することがあります。

Q5. 外部 API との連携で認証エラーが発生します

A. 環境変数に設定したトークンが有効期限を切れていないか確認し、正しい形式（Bearer トークンなど）でリクエストに含められているか検証してください。また、API のドメインやエンドポイントが変更されていないかも確認が必要です。

Q6. エラーハンドリングでスタックトレースが含まれません

A. 標準の console.log では詳細な情報を取得できない場合があります。エラーオブジェクトを JSON に変換して出力するか、ロギングライブラリ（Winston や Pino）を導入することで、より詳細なスタック情報を取得できます。

Q7. サンドボックス化は必須ですか

A. 必ずしも必須ではありませんが、推奨されます。特に外部ファイルやデータベースにアクセスするツールを実装する場合、悪意あるコードの実行を防ぐためにコンテナ化や制限された権限での実行を行うことで安全性を大幅に向上させられます。

Q8. 応答が遅い場合の原因は何ですか

A. 非同期処理が適切に行われていないか、ネットワーク遅延が原因である可能性があります。I/O 操作に await を使用していないとブロックされるため、確認してください。また、外部 API のレート制限により待機している可能性もあります。

Q9. マルチテナント対応は可能ですか

A. はい、可能です。MCP サーバー内で認証情報を管理し、リクエストごとにユーザーを識別して権限を分けるロジックを実装することで実現できます。ただし、セキュリティリスクが高まるため、監査ログの記録が必須となります。

Q10. MCP Spec v2.0 への対応はいつですか

A. 2026 年時点では v1.0 が安定版として広く採用されていますが、将来 v2.0 のリリースが予定されています。現在のプロダクション環境では v1.0 を使用し続けることが推奨されます。アップグレード時は公式ドキュメントの移行ガイドを参照してください。

まとめ

本記事では、[Model Context Protocol（MCP）サーバー開発の基礎から実践までを網羅的に解説しました。2026 年春時点の技術動向を反映させつつ、Anthropic の最新仕様に基づいた具体的な実装手順を提供しています。以下の要点を確認し、安全かつ高機能な AI エージェント環境を構築してください。

• MCP の基本概念: Resources（読み取り）、Tools（操作）、Prompts（指示）の 3 つを理解し、役割分担を明確にする
• トランスポート選択: ローカルには Stdio、Web には SSE/HTTP を使い分け、用途に適した通信方式を選ぶ
• SDK 選定: データ処理なら Python (mcp)、Web 連携なら TypeScript SDK を優先する
• セキュリティ対策: 最小権限の原則を徹底し、サンドボックス化と環境変数管理でリスクを低減する
• デバッグ手法: MCP Inspector を活用して通信フローを可視化し、ログ出力で状態を追跡する

これらの要素を組み合わせることで、Claude Desktop や [Claude Code とシームレスに連携する信頼性の高いツール群を開発できます。MCP プロトコルは急速に進化する技術ですが、本ガイドの基礎を押さえておくことで、将来の仕様のアップデートにも柔軟に対応することが可能となります。今後も AI エージェントエコシステムの発展に注目し、新しい機能を取り入れながら継続的な学習を心がけてください。