MCP AI コーディング セットアップの実戦用サーバー: 原則、構成、落とし穴の回避

MCP サーバーとは何ですか?エージェントのワークフローではどのような役割を果たしますか?

MCP (モデル コンテキスト プロトコル) サーバーは個別のマイクロサービスではありませんが、AI はエージェントと外部ツール (Git、ファイル システム、データベース、CLI コマンドなど) の間の標準化された通信層をエンコードします。エージェントを起動して「このモジュールのリファクタリングとテストの実行を手伝ってください」と言うと、エージェント自体には git Push または npm テストを直接実行する機能がありません。これらの操作をプロキシする MCP サーバーが必要です。

一般的なエージェントのワークフローでは、MCP サーバーは 3 つの責任を負います。

• 機能登録: 現在の環境で提供されているツール (read_file、write_file、run_command、search_web など) と各ツールの入力および出力パラメーター形式をエージェントに伝えます。
• セキュリティ サンドボックス: エージェントによって送信されたツール呼び出しリクエストは、最初に MCP サーバー権限の検証を通過します。たとえば、特定のディレクトリのみの読み取りを許可したり、危険性の高いコマンドの実行を禁止したりすることができます。
• 結果エコー: ツール実行後の出力 (ファイルの内容、コマンド stdout/stderr、戻りエラー) は、エージェントが理解して意思決定を継続できるように、構造化されたメッセージにフォーマットされます。

MCP サーバーを構築するための重要な手順

1. プロトコルの実装と言語を選択します

現在、主流のソリューションには、公式の TypeScript SDK とコミュニティが管理する Python SDK が含まれています。 AI コーディング環境が Node.js エコシステム (Cursor、Continue など) の場合は、TypeScript バージョンを使用することをお勧めします。 Python ファーストの Agent フレームワーク (LangChain、AutoGPT など) の場合は、Python バージョンを使用する方が面倒です。

実践的なパス:

• プロジェクトを初期化した後にテンプレートを使用します: npm create mcp-server@latest my-server または pip install mcp-server。
• コア コード構造: Tool コレクションを実装します。各ツールには名前、スキーマ (JSON スキーマ)、および実行関数 (非同期) が含まれます。

2. ツールと権限の境界を定義する

ここが最も問題が起こるところです。よくある間違いは、エージェントに「任意のファイルの書き込み」または「任意のシェルの実行」権限を与えることです。妥当な境界は次のとおりです。

• 現在のプロジェクト ディレクトリ内のファイルのみが読み書き可能となり、/etc、/root へのアクセスは禁止されます。
• rm -rf / ではなく、npm run build、python test.py などのホワイトリストに登録されたコマンドの実行のみを許可します。
• 機密性の高い操作 (ファイルの削除など) についてはユーザーの確認を必要とします。

実際のシナリオ: チームがフィルタリングせずに run_command ツールを開き、コードを生成した後、エージェントが同僚の提出物をカバーして git push --force を自動的に実行しました。これは、権限の境界が明確に設定されていないことが原因です。

3. エージェント フレームワークとの統合

さまざまなエージェント フレームワークがさまざまな方法で MCP サーバーに接続します。 Continue を例として、~/.continue/config.json で MCP サーバー エンドポイント (通常はローカルホスト ポート) を構成し、ツール リストを宣言します。次に、IDE でコードの一部を選択し、「エラー処理の追加」コマンドを入力します。エージェントは MCP サーバー経由でファイルを読み取り、コードを生成して、ファイルを書き戻します。

失敗しやすい: MCP サーバーの応答がタイムアウトすると (デフォルトは 30 秒)、エージェントは停止するか、不完全な結果を生成します。長時間実行されるタスク (依存関係のインストールなど) を非同期ステップに分割するか、タイムアウト構成を増やすことをお勧めします。

よくある誤解と解決策

誤解 1: ツールはすべてエージェントに丸投げする

開発者の中には、手間を省いて一度に 30 個のツールを登録したいと考えている人もいます。その結果、エージェントはツールの選択時に頻繁にエラーを起こします (間違ったパラメータを選択したり、間違った順序で呼び出したりする)。より良いアプローチは、現在のタスクに必要なツールのみを公開し、プロンプトでツールが使用される順序を説明することです。たとえば、リファクタリング タスクは 3 つのツール read_file、write_file、および run_test のみを公開します。

誤解 2: エラー処理の無視

MCP サーバーでのツールの実行が失敗する可能性があります (ファイルが存在しない、ネットワークが利用できない)。ツールの実装で構造化エラー メッセージ ({ status: "error", message: "File not found" } など) が返されない場合、エージェントは操作が成功したと誤って認識し、後続のロジックがクラッシュする可能性があります。すべてのツールは例外をキャッチし、明示的なエラー オブジェクトを返す必要があります。

誤解 3: 実稼働環境でデフォルト構成を直接使用する

デフォルトの MCP サーバー構成は、一般に、オープン権限を備えた開発に適しています。オンラインで使用する前に、次のことを行う必要があります。

• 不要なツールをすべて閉じます (例: delete_file、execute_sys_command)。
• allowed_pathsとblocked_commandsを設定します。
• 監査ログを有効にして、エージェントによるすべてのツール呼び出しを記録します。

失敗した場合のフォールバック計画

MCP サーバーが引き続き不安定な場合、またはエージェントのワークフローにセキュリティ リスクがあることが判明した場合は、一時的に「手動ツール」モードに戻すことができます。

• エージェントにはシェルコマンドのみを出力させ、手動でコピーして実行できます。
• または、自動実行ではなくコード生成のみを行う codex、inline assistant などのより軽量なソリューションを使用します。

これは後退ではなく、実稼働レベルの AI コーディング プロセスの多くは依然として「エージェントの提案 + 手動承認」のハイブリッド モデルを使用しています。

次に何をするか

ここで、MCP サーバーをローカルに構築してみます。最も単純な「ファイル ビューア」から始めて、最初にエージェントがファイルの内容を正しく読み取ることができるようにし、次に徐々に書き込み操作とコマンドの実行を追加します。ツールが追加されるたびに、同時リクエストと障害シナリオがシミュレートされ、エージェントがエラーを確実に理解できるようになります。

システムに AI プログラミング ワークフロー設計、品質管理、セキュリティ保護を習得させたい場合は、より完全なエージェント アーキテクチャと評価システムを詳しく検討することをお勧めします。