なぜ手で書くのか

MCP には公式の SDK があり、次の章ではそれを使います。ここであえて手で書くのには理由があります。

SDK を使うと 20 行ほどでサーバーが完成します。ところが、いざホストに登録して動かないとき、どこまで届いているのかが分かりません。プロセスは起動しているのか。初期化まで進んだのか。ツールの一覧は渡ったのか。SDK の内側で起きていることが見えないと、切り分けようがありません。

この章で JSON-RPC を 1 往復させておけば、以降どの章で詰まっても「どこまで来ているか」を自分で確かめられます。15 分の投資で、残りの時間が助かります。

標準入出力でやりとりする

MCP には運び方（トランスポート）が 2 つあります。ここで使うのは stdio です。

stdio の実体は改行区切りの JSONです。特別なライブラリは要りません。

受け取る側の骨組み

import { createInterface } from 'node:readline';

// stdout は JSON-RPC 専用。ログは stderr へ出す
function log(...args) {
	console.error('[minimal]', ...args);
}

// 1 メッセージ 1 行。末尾の改行が区切りになる
function send(message) {
	process.stdout.write(JSON.stringify(message) + '\n');
}

const rl = createInterface({ input: process.stdin });

rl.on('line', (line) => {
	if (!line.trim()) return;
	const request = JSON.parse(line);
	// ここで処理する
});

readline が改行で区切ってくれるので、こちらは 1 行ずつ受け取るだけです。

3 つのメソッドに答える

最低限のサーバーが答えるべきメソッドは 3 つです。

ツールの品書き

tools/list で返す内容です。inputSchema は JSON Schema で書きます。モデルはこの説明だけを頼りに呼ぶので、description は人に説明するつもりで書きます。

const TOOLS = [
	{
		name: 'add',
		description: '2 つの数を足す',
		inputSchema: {
			type: 'object',
			properties: {
				a: { type: 'number', description: '1 つめの数' },
				b: { type: 'number', description: '2 つめの数' },
			},
			required: ['a', 'b'],
		},
	},
];

3 つに答える

function handle(request) {
	const { id, method, params } = request;

	switch (method) {
		// ホストが最初に送ってくる。名乗り合いをする
		case 'initialize':
			return reply(id, {
				// 相手が送ってきたバージョンをそのまま返す
				protocolVersion: params?.protocolVersion ?? '2025-06-18',
				capabilities: { tools: {} },
				serverInfo: { name: 'minimal', version: '1.0.0' },
			});

		// 提供するツールの一覧を返す
		case 'tools/list':
			return reply(id, { tools: TOOLS });

		// ツールを実行する
		case 'tools/call': {
			if (params?.name !== 'add') {
				return replyError(id, -32602, `unknown tool: ${params?.name}`);
			}
			const { a, b } = params.arguments ?? {};
			if (typeof a !== 'number' || typeof b !== 'number') {
				// 引数が不正なときは、プロトコルのエラーではなく結果として返す
				return reply(id, {
					content: [{ type: 'text', text: 'a と b には数値を渡してください' }],
					isError: true,
				});
			}
			return reply(id, {
				content: [{ type: 'text', text: String(a + b) }],
			});
		}

		default:
			return replyError(id, -32601, `method not found: ${method}`);
	}
}

全体は samples/02-minimal/server.mjs にあります。90 行ほどです。

動かす

ホストに登録する前に、手で叩いて確かめます。標準入力に JSON を流し込むだけです。

@(
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"手","version":"1.0"}}}'
'{"jsonrpc":"2.0","method":"notifications/initialized"}'
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add","arguments":{"a":2,"b":3}}}'
) -join "`n" | node server.mjs

実際の出力です。

[minimal] 起動した
[minimal] 受信: {"jsonrpc":"2.0","id":1,"method":"initialize",...}
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"tools":{}},"serverInfo":{"name":"minimal","version":"1.0.0"}}}
[minimal] 受信: {"jsonrpc":"2.0","method":"notifications/initialized"}
[minimal] 通知: notifications/initialized
[minimal] 受信: {"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"add","description":"2 つの数を足す",...}]}}
[minimal] 受信: {"jsonrpc":"2.0","id":3,"method":"tools/call",...}
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"5"}]}}

[minimal] が付いている行は stderr、付いていない行が stdout です。混ざって見えていても、実際には別の流れです。

stdout を汚さない

MCP サーバーで最も多い事故がこれです。

// これをやると壊れる
console.log('サーバーを起動しました');

console.log は stdout に書きます。stdout は JSON-RPC の通り道なので、ホストはこの行をメッセージとして読もうとします。JSON として読めないので、その接続は成立しません。

対策

次の章へ

ここまでで、MCP サーバーが何をしているかは全部見えました。次は同じものを SDK で書き直し、何が省けるのかを確かめます。