読者が抱える課題
AIエージェントやLLMを活用したツール開発において、外部システム（データベース、ローカルファイル、外部APIなど）との連携処理をモデルごとに個別実装すると、保守性が低下し汎用性が失われるという課題があります。ツール連携のインターフェースが標準化されていない場合、新しいLLMクライアントやAIエージェントを導入するたびにコネクタを再構築する必要があります。
この記事で分かること
- Anthropicがオープンソースとして公開した**MCP（Model Context Protocol）**の基本構造
- Python SDK（
mcppackage）を使用したカスタムMCPサーバーの実装方法 - MCPサーバーの接続確認とデバッグ手順
- 実務導入時におけるセキュリティ・運用上の注意点
対象読者・前提条件
- 対象読者: LLMを活用したシステム開発を行うエンジニア、Pythonでのツール連携実装を行いたい方
-
前提条件:
- Python 3.10 以上がインストールされていること
- Claude Desktop などのMCPクライアント環境が用意されていること（設定確認用）
MCP（Model Context Protocol）とは
MCP（Model Context Protocol）は、LLMアプリケーションと外部データソースやツールを標準化されたインターフェースで接続するためのオープンプロトコルです。Web開発におけるRESTやGraphQLのように、LLMと外部機能を分離して結合度を下げる役割を果たします。
主な要素
- MCP Client: ユーザーの入力を受け取り、LLMとの通信やMCPサーバーへのリクエスト制御を行う（例: Claude Desktop, Cursor等）
- MCP Server: 外部ツール、プロンプト、リソース（データ）を定義し、Clientからのリクエストに応じて実行・レスポンスを返すプログラム
- Transport: ClientとServer間の通信層（stdio, HTTP with SSE など）
PythonによるカスタムMCPサーバーの実装例
ここでは、Python公式の mcp SDK を利用して、指定したディレクト内のファイル一覧を取得するシンプルなMCPサーバーを作成します。
1. 依存ライブラリのインストール
uv または pip を使用して必要なパッケージをインストールします。
pip install mcp
2. MCPサーバーの実装コード
以下は、標準入力・出力（stdio）経由で通信するMCPサーバーの実装例です。
import os
from typing import List
from mcp.server.fastmcp import FastMCP
# FastMCPインスタンスの初期化（独自MCPサーバーの定義）
mcp = FastMCP("DirectoryScanner")
@mcp.tool()
def list_files(directory_path: str) -> List[str]:
"""指定されたディレクトリ内のファイルおよびフォルダの一覧を取得します。
Args:
directory_path: ファイル一覧を取得したいディレクトリの絶対パス
"""
# 実務では入力値検証を実施してパス・トラバーサル等を防止します
if not os.path.exists(directory_path):
raise ValueError(f"指定されたパスが存在しません: {directory_path}")
if not os.path.isabs(directory_path):
raise ValueError("絶対パスを指定してください。")
return os.listdir(directory_path)
if __name__ == "__main__":
# stdio トランスポートでサーバーを実行
mcp.run(transport="stdio")
※注意: 上記コードは説明用の独自実装例です。実際に動作させる環境に合わせてパスの検証論理などを補強してください。
Claude Desktopへの設定例（JSON）
作成したMCPサーバーを Claude Desktop に登録する場合の設定例（claude_desktop_config.json）です。
{
"mcpServers": {
"directory-scanner": {
"command": "python",
"args": [
"/absolute/path/to/your_server.py"
]
}
}
}
※ OSや環境（uv や venv を使用する場合）に応じて command や args のパスを適切に変更してください。
トラブルシューティングとデバッグ手順
MCPサーバーが正しく起動・接続できない場合は、以下の順序で確認を行います。
-
単体実行の確認
- ターミナルから直接 Python スクリプトを実行し、構文エラーや依存関係の不足がないか確認します。
-
MCP Inspector の利用
- MCP公式が提供するデバッグツール
npx @modelcontextprotocol/inspectorを使用して、stdio経由でツールが正しくリスンしているかテストします。
npx @modelcontextprotocol/inspector python /absolute/path/to/your_server.py - MCP公式が提供するデバッグツール
-
ログの確認
- Client側のログ（Claude Desktopの場合はアプリのログフォルダ）を確認し、MCPサーバー起動時のエラーメッセージを取得します。
導入時の注意点・チェックリスト
実務環境にMCPを導入・運用する際は、以下のチェック項目を確認してください。
| チェック項目 | 内容 | 対策 |
|---|---|---|
| アクセス権限の最小化 | MCPサーバーに不必要なファイルアクセスやAPI実行権限を与えない | 読み取り専用権限の設定や、参照可能ディレクトリの制限を行う |
| 入力値の検証 | LLMから渡される引数が意図しない命令を含んでいないか | コマンドインジェクションやパス・トラバーサル攻撃を防ぐバリデーションを入れる |
| タイムアウト処理 | 外部API連携時の非応答によるプロセスフリーズ | クライアントおよびサーバー側で適切なタイムアウト時間を設定する |
| 仕様変更への追従 | MCP仕様およびSDKの更新速度が速い | 実装・運用時には常にMCP公式ドキュメントの最新情報を確認する |
まとめ
MCP（Model Context Protocol）を導入することで、LLMアプリケーションと外部ツールの連携部分を標準化し、コードの再利用性と保守性を向上させることができます。実装の際はセキュリティ上の検証（特にツールに渡される引数のチェック）を十分に行い、安全な構成で運用を開始してください。