はじめに
MCPサーバーでログを出すときの注意点を、学習メモとしてまとめました。仕様で決められた出力先を確認し、ログの出し方によってツールの呼び出し結果がどう変わるかを試します。
MCPは、AIアプリからツールなどを利用するための仕組みです。接続方法の一つであるstdioでは、クライアントとMCPサーバーが標準入力・標準出力でメッセージをやり取りします。標準出力には、画面に表示する文字ではなく、クライアントが読み取る通信データを出します。
動作確認のために console.log('echo started') を追加すると、この通信データにログが混ざります。小さなechoツールで出力先やログの形式を変え、呼び出し結果とクライアントに届いた出力を比較します。
対象はNode.jsでstdioのMCPサーバーや起動ラッパーを作る方です。JavaScriptとJSONの基本を前提に、標準出力と標準エラー出力の役割から説明します。実験には公式TypeScript SDK 2.2.0とテスト用の文字列を使います。業務で発生した障害の事例ではありません。LLMや有料APIは使いません。
標準出力は通信に、標準エラー出力はログに使う
MCP 2026-07-28のstdio仕様では、クライアントがサーバーを子プロセスとして起動します。サーバーは標準入力(stdin)で要求を受け、標準出力(stdout)で応答や通知を返します。メッセージの区切りは改行です。stdoutに診断ログなどの別の文字列を混ぜることは認められていません。
たとえば、次の出力では最初の行もクライアントに届きます。
echo started
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"hello"}]}}
1行目のecho startedは、MCPのメッセージではありません。クライアントにはこの行も通信データとして届くため、受信側での処理に影響します。
ログには、標準出力とは別の標準エラー出力(stderr)を使います。名前に「エラー」とありますが、エラー以外の診断ログにも使える出力先です。
Node.jsの標準consoleでは、console.log()、console.info()、console.debug()がstdoutを使います。console.error()とconsole.warn()はstderrを使います。このため、MCPのstdioでは、情報やデバッグ用のログにもconsole.error()などを使えます。仕様でも、stderrに出力があっただけでクライアントが処理失敗と判断してはいけないとされています。
ログの出し方を変えて、呼び出し結果を比較する
公式SDKのClientとStdioClientTransportから、別プロセスのMcpServerとserveStdioを呼び出しました。ツールはテスト用の文字列first\nsecondをそのまま返すだけです。違いはログの出力先・形式と、応答の整形方法に限定しています。
クライアントはプロトコル2026-07-28へ固定しました。SDK v2.2.0ではこの指定でも接続時に検出用の子プロセスが起動されるため、通常の通信だけでなく、その検出用プロセスの出力も記録します。ツール呼び出しは各ケース1回です。
各ケースで、次の3点を確認しました。
-
callTool()が結果を返すか、500msの待機上限に達するか -
client.onerrorが何回呼ばれるか - クライアントへ届くstdoutに、JSONまたはJSON-RPCの形式として不正な行があるか
stdoutはNode.jsの中継プロセスでそのまま保存し、クライアントへ転送します。中継で不正な行を取り除くと、クライアントに届く出力が変わってしまうためです。
| ツール実行時の出力 | 呼び出し結果 | client.onerror | stdoutの行検査 |
|---|---|---|---|
| ログなし | 成功 | 0件 | 通過 |
| stderrへ平文ログ | 成功 | 0件 | 通過 |
| stdoutへ平文ログ+改行 | 成功 | 0件 | JSON構文エラー1行 |
| stdoutへJSONログ+改行 | 成功 | 1件 | JSON-RPC形式エラー1行 |
| stdoutへ改行なしの平文ログ | タイムアウト | 0件 | JSON構文エラー1行 |
| ツール応答をpretty-print | タイムアウト | 0件 | JSON構文エラー19行 |
| stderrのログをラッパーでstdoutへ合流 | 成功 | 0件 | JSON構文エラー1行 |
2026-10-01 UTC、Linux x64、Node.js v24.19.0、SDK client/server/core 2.2.0、Zod 4.6.5で確認しました。7ケースとも、表の結果と一致することをテストで確認しています。タイムアウトした2ケースも、その結果になることをテストで確認しています。
stdoutへ平文ログを出したケースでは、呼び出しが成功し、エラー通知もありませんでした。記録したstdoutを読むと、ログの1行が混ざっていました。この動作は、SDKが不正な行を読み飛ばす処理で説明できます。
平文ログとJSONログでエラー通知が違った理由
SDK 2.2.0のReadBufferの実装は、改行までの1行を取り出し、その行を消費してからJSONとして読み込みます。JSONの構文エラーであるSyntaxErrorが起きると、その行を読み飛ばして次へ進みます。
そのため、echo startedのような平文ログが独立した行にある場合は、続く正しい応答を読めます。この経路ではclient.onerrorも呼ばれませんでした。
一方、次のログはJSONとしては正しいものの、JSON-RPCのメッセージにはなっていません。
{"level":"info","message":"echo started"}
これはSDKのスキーマ検証で失敗します。StdioClientTransportの受信ループは、その例外をエラーハンドラーへ渡した後も次の行を読みます。今回のクライアントはエラーを記録するだけなので、後続の応答を受け取ってツール呼び出しを完了しました。
今回のSDKでは、不正なログの行を処理した後も、続く応答を受け取れました。ログが混ざっても呼び出しが成功したのはこのためです。他のクライアントや、エラー時に接続を閉じるアプリケーションでは、結果が異なる可能性があります。
改行なしのログでは、応答も読み取れなかった
改行なしで診断文字列を書いたケースでは、その後にSDKが書く応答と同じ物理行になりました。
echo started: {"jsonrpc":"2.0","id":1,"result":{...}}
SDKは改行までを一つのJSONとして読むため、ログと応答を分けられません。行全体が構文エラーになり、応答も読み飛ばされます。サーバーのツール処理は結果を返しているのに、クライアントは対応する応答を受け取れずタイムアウトしました。
pretty-printも、メッセージ途中に実際の改行を挿入します。ファイル全体なら正しいJSONでも、1行ずつ読むstdioの区切り方には合いません。実験ではツール応答だけをJSON.stringify(message, null, 2)で整形し、19行すべてがJSON構文エラーになりました。この行数は今回の応答とSDK版に固有です。
なお、文字列の中身に改行があることは別の話です。JSON.stringify()は文字列内の改行を\nへエスケープします。成功したケースではfirst\nsecondが、改行を含む元の文字列として戻ることも検査しています。
ログの行き先は起動コマンドまで確認する
サーバー内部では、プロトコルの出力をSDKに任せ、診断ログをstderrへ出すのが基本です。log()というメソッド名を使いたい場合は、専用のConsoleを作れます。
import { Console } from 'node:console';
const logger = new Console({
stdout: process.stderr,
stderr: process.stderr,
});
logger.log('echo started');
これだけでは、起動ラッパーの出力は制御できません。今回の7ケース目では、サーバーはconsole.error()を使っていても、中継でstderrをstdoutへ合流させると不正な行が届きました。シェルの2>&1に相当する合流をNode.jsのストリームで再現したものです。実際のシェルごとの挙動を試した結果ではありません。
stdoutにログが混ざる場合は、サーバー本体のログ設定だけでなく、起動コマンドや依存ライブラリも確認します。起動バナーが出ていないか、stderrをstdoutへリダイレクトしていないかも確認が必要です。グローバルなconsole.logの差し替えだけでは、直接のprocess.stdout.writeや子プロセスの出力は防げません。
ログをstderrへ変更しても、認証情報や本文データを無条件に出してよいわけではありません。出力先にかかわらず、ログに残す情報には注意が必要です。
呼び出し結果とstdoutを確認する
テストではツールの呼び出し結果を確認するとともに、クライアントに届いたstdoutを保存します。保存した出力について、各行がJSONとして読めるか、JSON-RPCの形式に合っているかを調べます。末尾に改行のない文字列が残っていないかも確認します。
JSON-RPCの形式の検査には、SDKのJSONRPCMessageSchemaを使いました。平文ログはJSONの読み込み時に、JSON形式のアプリケーションログはこのスキーマ検証で検出できます。
この検査で確認するのは、stdoutの形式です。通知名や内容の意味、要求と応答の対応、文字コードの異常、エラー後の回復までを網羅するものではありません。また、今回実行しなかった経路で出るログは確認できません。実際のサーバーを調べる際は、起動時や正常終了時、エラー発生時など、それぞれの出力を採取します。
手元で7ケースを再現する
次の3ファイルを同じディレクトリへ保存し、Node.js 24で実行します。ファイル名はコードブロックの見出しに合わせます。SDKとZodは版を固定し、インストール後に生成されるlockfileも保存してください。
npm init -y
npm install --save-exact @modelcontextprotocol/client@2.2.0 @modelcontextprotocol/server@2.2.0 @modelcontextprotocol/core@2.2.0 zod@4.6.5
node --test --test-reporter=tap integration.test.mjs
初回の依存取得後、実験中は外部サービスへ接続しません。成功すると7テストが通り、results/integration.jsonに生出力・観測結果・実行環境が保存されます。生出力には検出用の応答も含まれます。500msは今回のローカル実験の待機上限であり、実運用に勧めるタイムアウト値ではありません。
server.mjs
import { Writable } from 'node:stream';
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio, StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
const mode = process.argv[2] ?? 'clean';
// Deliberate fault injection: change only tool-result serialization, not discovery.
const output = mode === 'pretty' ? new Writable({
write(chunk, encoding, callback) {
const message = JSON.parse(chunk.toString());
const bytes = message.result?.content
? JSON.stringify(message, null, 2) + '\n'
: chunk;
process.stdout.write(bytes, callback);
},
}) : process.stdout;
serveStdio(() => {
const server = new McpServer({ name: 'stdio-logging-lab', version: '1.0.0' });
server.registerTool('echo', {
description: 'Echo synthetic text without external I/O',
inputSchema: z.object({ text: z.string() }),
}, async ({ text }) => {
if (mode === 'stderr') console.error('echo started');
if (mode === 'stdout-line') console.log('echo started');
if (mode === 'stdout-json') console.log(JSON.stringify({ level: 'info', message: 'echo started' }));
if (mode === 'stdout-prefix') process.stdout.write('echo started: ');
return { content: [{ type: 'text', text }] };
});
return server;
}, {
legacy: 'reject',
transport: new StdioServerTransport(process.stdin, output),
onerror: error => console.error(error.message),
});
record-process.mjs
// Transparent recorder around the real server process. No JSON parsing here.
// The optional merge flag deliberately models a shell wrapper's `2>&1`.
import { spawn } from 'node:child_process';
import { appendFileSync } from 'node:fs';
import { Transform } from 'node:stream';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const [directory, mode, merge] = process.argv.slice(2);
const child = spawn(process.execPath, [fileURLToPath(new URL('./server.mjs', import.meta.url)), mode], {
stdio: ['pipe', 'pipe', 'pipe'],
});
function record(name) {
return new Transform({
transform(chunk, encoding, callback) {
appendFileSync(path.join(directory, name), chunk);
callback(null, chunk);
},
});
}
process.stdin.pipe(record('stdin.jsonl')).pipe(child.stdin);
const outbound = record('stdout.txt');
outbound.pipe(process.stdout, { end: false });
const errors = child.stderr.pipe(record('stderr.txt'));
if (merge === 'merge') {
// Record AFTER the merge, preserving the order actually sent to the client.
child.stdout.pipe(outbound, { end: false });
errors.pipe(outbound, { end: false });
let openStreams = 2;
const ended = () => { if (--openStreams === 0) outbound.end(); };
child.stdout.on('end', ended);
errors.on('end', ended);
} else {
child.stdout.pipe(outbound);
errors.pipe(process.stderr, { end: false });
}
child.stdin.on('error', error => {
if (error.code !== 'EPIPE') console.error(error.message);
});
child.on('error', error => {
console.error(error.message);
process.exitCode = 1;
process.stdin.destroy();
});
child.on('close', code => {
process.exitCode = code ?? 1;
process.stdin.destroy();
});
process.on('SIGTERM', () => child.kill('SIGTERM'));
process.on('SIGINT', () => child.kill('SIGINT'));
integration.test.mjs
import test from 'node:test';
import assert from 'node:assert/strict';
import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { Client, SdkErrorCode } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
import { JSONRPCMessageSchema } from '@modelcontextprotocol/core';
const reports = [];
const output = new URL('./results/', import.meta.url);
await fs.mkdir(output, { recursive: true });
const cases = [
{ mode: 'clean', outcome: 'success', errorCount: 0, syntaxErrors: 0, schemaErrors: 0 },
{ mode: 'stderr', outcome: 'success', errorCount: 0, syntaxErrors: 0, schemaErrors: 0 },
{ mode: 'stdout-line', outcome: 'success', errorCount: 0, syntaxErrors: 1, schemaErrors: 0 },
{ mode: 'stdout-json', outcome: 'success', errorCount: 1, syntaxErrors: 0, schemaErrors: 1 },
{ mode: 'stdout-prefix', outcome: 'timeout', errorCount: 0, syntaxErrors: 1, schemaErrors: 0 },
{ mode: 'pretty', outcome: 'timeout', errorCount: 0, syntaxErrors: 19, schemaErrors: 0 },
{ mode: 'stderr', merge: true, outcome: 'success', errorCount: 0, syntaxErrors: 1, schemaErrors: 0 },
];
function inspectWire(stdout) {
const lines = stdout.split('\n');
const trailingBytes = lines.pop();
let syntaxErrors = 0;
let schemaErrors = 0;
for (const line of lines) {
let value;
try { value = JSON.parse(line.replace(/\r$/, '')); }
catch { syntaxErrors++; continue; }
if (!JSONRPCMessageSchema.safeParse(value).success) schemaErrors++;
}
return { lines: lines.length, syntaxErrors, schemaErrors, trailingBytes };
}
for (const expected of cases) {
const name = expected.merge ? 'stderr-merged-to-stdout' : expected.mode;
test(name, { timeout: 15000 }, async () => {
const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-stdio-lab-'));
const errors = [];
const transport = new StdioClientTransport({
command: process.execPath,
args: [fileURLToPath(new URL('./record-process.mjs', import.meta.url)), directory,
expected.mode, expected.merge ? 'merge' : 'separate'],
stderr: 'pipe',
});
let receivedStderr = '';
transport.stderr.on('data', chunk => { receivedStderr += chunk.toString(); });
const client = new Client({ name: 'stdio-test-client', version: '1.0.0' }, {
versionNegotiation: { mode: { pin: '2026-07-28' } },
});
client.onerror = error => errors.push({ name: error.name, message: error.message });
let outcome;
let response;
let requestError;
try {
await client.connect(transport, { timeout: 3000 });
try {
response = await client.callTool({ name: 'echo', arguments: { text: 'first\nsecond' } }, { timeout: 500 });
outcome = 'success';
} catch (error) {
requestError = { name: error.name, code: error.code, message: error.message };
outcome = error.code === SdkErrorCode.RequestTimeout ? 'timeout' : 'other-error';
}
} finally {
await client.close();
}
const read = async name => fs.readFile(path.join(directory, name), 'utf8').catch(error => {
if (error.code === 'ENOENT') return '';
throw error;
});
const stdout = await read('stdout.txt');
const stderr = await read('stderr.txt');
const stdin = await read('stdin.jsonl');
const wire = inspectWire(stdout);
const report = { name, outcome, response, requestError, clientErrors: errors, wire, stdout, stderr, receivedStderr };
reports.push(report);
await fs.rm(directory, { recursive: true, force: true });
assert.equal(outcome, expected.outcome);
if (outcome === 'success') assert.deepEqual(response.content, [{ type: 'text', text: 'first\nsecond' }]);
const requests = stdin.trim().split('\n').map(JSON.parse);
const calls = requests.filter(message => message.method === 'tools/call');
assert.equal(calls.length, 1);
assert.equal(calls[0].params._meta['io.modelcontextprotocol/protocolVersion'], '2026-07-28');
assert.equal(errors.length, expected.errorCount);
assert.equal(wire.syntaxErrors, expected.syntaxErrors);
assert.equal(wire.schemaErrors, expected.schemaErrors);
assert.equal(wire.trailingBytes, '');
assert.equal(stderr, expected.mode === 'stderr' ? 'echo started\n' : '');
assert.equal(receivedStderr, expected.mode === 'stderr' && !expected.merge ? stderr : '');
});
}
test.after(async () => fs.writeFile(new URL('integration.json', output), JSON.stringify({
verifiedAt: new Date().toISOString(), node: process.version, platform: process.platform, arch: process.arch,
sdk: { client: '2.2.0', server: '2.2.0', core: '2.2.0', zod: '4.6.5' },
protocolVersion: '2026-07-28', requestTimeoutMs: 500,
scope: 'official SDK client and server in separate processes with transparent byte recorder',
reports,
}, null, 2) + '\n'));
検証の範囲
この記事では、SDK 2.2.0でログや応答の出力方法を変えた7ケースを確認しました。クライアントの種類やバージョンを横断した互換性比較、Streamable HTTP、実際のLLMホスト、Windowsでのプロセス終了、複数ツールの同時実行は対象外です。
今回の実験では、ツールが結果を返していても、stdoutにログが混ざっているケースがありました。呼び出し結果だけでは分からないログの混入も、保存したstdoutを読むことで確認できました。
参考資料
- MCPのstdio仕様:メッセージの区切り、stdoutの制約、stderrの扱い。
- Node.js v24.19.0のConsole:各consoleメソッドの出力先と専用Consoleの設定。
- TypeScript SDK 2.2.0相当のReadBuffer実装:改行による区切りとJSON構文エラーの読み飛ばし。
- 同SDKのStdioClientTransport受信ループ:例外の通知と、その後の読み取り継続。
仕様の説明は上記の一次資料に基づきます。結果表とタイムアウトの観測は、本記事の固定版・実験条件に限ったものです。