Model Context Protocol (MCP) の仕組みと自作サーバー開発
Model Context Protocol (MCP) の基本概念、JSON-RPC、stdio/SSE通信、ツールとリソースの設計、TypeScriptによる自作MCPサーバー開発を徹底解説。
AIエージェントやコーディングアシスタントが日常の開発フローに浸透する中、エンジニアが直面してきた大きな課題があります。それは、「社内データや各種API、ファイルシステムを、モデルごとに個別の連携コードを書かずにどう安全に接続するか」という問題です。
この課題を解決するためにAnthropicがオープンソースとして提唱した標準規格が、Model Context Protocol (MCP) です。
なぜ今、MCPが必要なのか?#
MCP登場以前、AIエコシステムは典型的な の統合課題 に悩まされていました:
- 個のAIクライアント(Claude Desktop、Cursor、VS Code、ターミナルエージェントなど)
- 個のデータソース・ツール(PostgreSQL、GitHub、Slack、ローカルファイルなど)
- 各クライアントとツールの組み合わせごとに、合計 通りのプラグイン開発と保守が必要でした。
新しいLLMやツールが登場するたびに、ゼロから連携コードを作り直す必要があったのです。
[!NOTE] MCPによる解決策:連携の複雑さを から へと劇的に低減します。MCPはAIアプリケーションにとっての 「USB-Cポート」 のような役割を果たします。MCPをサポートするクライアントであれば、既存のあらゆるMCPサーバーへ即座にプラグイン可能です。
10歳でもわかるMCPの考え方(ELI5)#
AIモデルを「窓のない部屋にいる博識な教授」に例えてみましょう:
- Host & Client(窓口となる秘書):Claude Desktopやエディタが教授の隣で指示を仲介します。
- MCP Server(外部につながる専用の引き出し):それぞれのMCPサーバーは外部世界へ通じる引き出しです。社内文書が入った引き出し、計算機、GitHubリポジトリへ接続する引き出しなどがあります。
- JSON-RPC(標準化された伝票):教授がデータを読んだり操作を実行したい時、共通フォーマットの伝票(JSON-RPCメッセージ)を発行し、引き出し側が正確に結果を返します。
MCPが提供する3つの基本要素(Primitives)#
MCPプロトコルは、サーバーがクライアントに提供できる3つの基本機能を定めています:
1. Tools(モデル主導のアクション)#
LLMが主動して呼び出す実行可能関数です(例:データベース検索、Bashスクリプトの実行、Slack通知)。モデルは公開されたJSON Schemaに基づき、いつどのツールをどの引数で呼ぶかを自律的に決定します。
2. Resources(アプリ主導の読み取り専用データ)#
file:///var/logs/app.log や postgres://users/schema のように、一意のURIを持つ参照データです。クライアントやユーザーがコンテキストとしてLLMに添付し、確実なファクト情報を提供します。
3. Prompts(ユーザー主導の定型テンプレート)#
特定の反復タスク(例:「プルリクエストのレビュー」「障害ログの解析」など)を素早く実行するための引数付きプロンプトひな形です。
トランスポート方式(通信プロトコル)#
MCPは主に以下の2つのトランスポートをサポートしています:
- stdio(標準入出力):ローカルプロセスの通信に最適です。クライアントがサーバーを子プロセスとして起動し、
stdinからリクエストを送り、stdoutからレスポンスを受け取ります。ネットワーク遅延ゼロで安全です。 - SSE(Server-Sent Events) over HTTP:クラウドやリモート環境にホストされたサーバー向けです。クライアントはHTTP POSTで要求を送り、永続化されたSSEストリームからデータを受信します。
TypeScriptで自作MCPサーバーを実装する#
公式の @modelcontextprotocol/sdk を用いた、実践的で即座に動くMCPサーバーの作成例です:
- 設定参照リソース (
config://app-info) - リポジトリのファイル分析ツール (
analyze_workspace)
1. プロジェクトのセットアップ#
mkdir my-custom-mcp-server
cd my-custom-mcp-server
bun init -y
bun add @modelcontextprotocol/sdk zodbash2. サーバーの実装コード#
src/index.ts を作成します:
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ListResourcesRequestSchema,
ListToolsRequestSchema,
ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
import { z } from 'zod';
// サーバーの初期化
const server = new Server(
{
name: 'project-analytics-server',
version: '1.0.0',
},
{
capabilities: {
resources: {},
tools: {},
},
},
);
// 1. 利用可能リソースの登録
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: 'config://app-info',
name: 'プロジェクト構成情報',
mimeType: 'application/json',
},
],
};
});
// リソース取得ハンドラー
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
if (request.params.uri === 'config://app-info') {
return {
contents: [
{
uri: 'config://app-info',
mimeType: 'application/json',
text: JSON.stringify(
{
projectName: 'Dopana Engineering Hub',
environment: 'production',
supportedEngines: ['Bun', 'Node.js', 'Rust'],
},
null,
2,
),
},
],
};
}
throw new Error(`リソースが見つかりません: ${request.params.uri}`);
});
// 2. 利用可能ツールの登録
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: 'analyze_workspace',
description: 'ワークスペース内のファイル統計を分析します',
inputSchema: {
type: 'object',
properties: {
fileExtension: {
type: 'string',
description: '分析対象の拡張子 (例: ts, rs, py)',
},
},
required: ['fileExtension'],
},
},
],
};
});
// ツール実行ハンドラー
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === 'analyze_workspace') {
const ext = String(request.params.arguments?.fileExtension || 'ts');
return {
content: [
{
type: 'text',
text: JSON.stringify({
targetExtension: ext,
totalFilesFound: 42,
status: 'healthy',
summary: `.${ext} ファイルの解析が正常に完了しました`,
}),
},
],
};
}
throw new Error(`未定義のツールです: ${request.params.name}`);
});
// stdioトランスポートで起動
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('MCP Server が stdio 経由で正常に起動しました');
}
main().catch((err) => {
console.error('サーバー起動エラー:', err);
process.exit(1);
});typescript[!TIP] stdio通信での最重要注意点:ログ出力には必ず
stderr(console.error) を使用してください。stdoutはJSON-RPC通信専用のチャンネルです。stdoutに余計な文字列を出力すると、クライアント側でJSONパースエラーが発生します。
3. Claude Desktopとの連携設定#
claude_desktop_config.json に設定を追記します:
{
"mcpServers": {
"project-analytics": {
"command": "bun",
"args": ["run", "/absolute/path/to/my-custom-mcp-server/src/index.ts"]
}
}
}jsonアプリを再起動すると金づちアイコンが表示され、Claudeが会話の文脈に応じて analyze_workspace を自動で呼び出せるようになります。
まとめ#
Model Context Protocol(MCP)は単なる一企業の独自機能ではなく、言語モデルと外部世界を切り離して再利用性を最大化するオープンな次世代インフラです。MCPを採用することで、開発者は特定のAIプロバイダーに縛られることなく、堅牢で持続可能なツールエコシステムを構築できます。