Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

stdoutに非JSON行を出力するstdio MCPサーバーが最初の非JSON行で切断される問題（2.1.105のリグレッション）を修正しました。

原文（英語） ​

Fixed stdio MCP servers that print stray non-JSON lines to stdout being disconnected on the first stray line (regression in 2.1.105).

概要 ​

Claude Code v2.1.110では、stdioトランスポートで動作するMCPサーバーがstdoutに非JSON行（デバッグメッセージ、ログ、起動時のバナーなど）を出力した場合に、最初の非JSON行が検出された時点でサーバー接続が切断されてしまう問題が修正されました。この問題はv2.1.105で導入されたリグレッションでした。多くのMCPサーバーは起動時やデバッグ時に非JSON形式のテキストをstdoutに出力することがあり、この修正によってそのようなサーバーとの互換性が回復されます。

基本的な使い方 ​

この修正はバグフィックスのため、v2.1.110へのアップデートで自動的に改善されます。v2.1.105以降でMCPサーバーが突然切断される問題が発生していたユーザーは、アップデートで解消されます。

bash
# アップデート
npm update -g @anthropic-ai/claude-code

# MCPサーバーの接続状態確認
claude mcp list

実践例 ​

ユースケース1: デバッグ出力を持つMCPサーバー ​

python
# mcp-server-with-debug.py
# デバッグ情報をstdoutに出力するMCPサーバーの例

import sys
import json

# 起動時のデバッグメッセージ（非JSON行）
print("MCP Server starting...", flush=True)  # ← 非JSON行
print("Loading configuration...", flush=True)  # ← 非JSON行
print("Server ready!", flush=True)  # ← 非JSON行

# 通常のMCPプロトコル通信（JSON）
while True:
    line = sys.stdin.readline()
    if not line:
        break
    request = json.loads(line)
    response = handle_request(request)
    print(json.dumps(response), flush=True)  # ← JSON行
// v2.1.105〜v2.1.109の動作（バグあり）:
// "MCP Server starting..." を受信 → 非JSONとして検出 → 即座に切断

// v2.1.110以降の動作（修正済み）:
// 非JSON行はスキップして、JSON行のみプロトコルとして処理
// MCPサーバーは正常に動作し続ける

ユースケース2: ログ出力があるMCPサーバーの設定 ​

json
// .claude/settings.json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["./mcp-server.py"],
      "transport": "stdio"
    }
  }
}

v2.1.110以降、起動時にログを出力するサーバーでも接続が維持されます。

ユースケース3: MCPサーバー開発時のベストプラクティス ​

python
# 推奨: デバッグ出力はstderrに送る（非JSON行をstdoutに出さない）
import sys

# 非推奨（stderrへ）
print("Debug message", file=sys.stderr)  # 安全

# 非推奨だが許容（stderrへ）
sys.stderr.write("Starting server\n")  # 安全

# v2.1.110以降は許容（stderrを使うことが推奨）
print("Non-JSON startup message", flush=True)  # 許容されるようになった

ユースケース4: 接続問題のデバッグ ​

bash
# MCP接続問題を診断
CLAUDE_DEBUG=mcp claude 2>&1 | head -50

# 特定のMCPサーバーの接続テスト
claude mcp test my-server

# MCPサーバーのログを確認
claude mcp logs my-server

ユースケース5: バナー付きMCPサーバーの例 ​

bash
#!/bin/bash
# mcp-bash-server.sh
# 起動バナーを表示するMCPサーバー

echo "=============================="
echo "  My MCP Server v1.0.0"
echo "  Copyright 2026 Example Corp"
echo "=============================="

# v2.1.105〜2.1.109: 上記バナーで切断されていた
# v2.1.110以降: バナーをスキップしてプロトコル通信を継続

# MCPプロトコルのメインループ
while IFS= read -r line; do
  # JSONリクエストを処理
  echo "$line" | python3 handle_request.py
done

注意点 ​

  • リグレッションについて — この問題はv2.1.105で導入されたリグレッションでした。v2.1.104以前では発生していませんでした。
  • 影響を受けたバージョン — v2.1.105〜v2.1.109が影響を受けていました。
  • 非JSON行の扱い — 修正後も、非JSON行は適切に無視されMCPプロトコルの通信には影響しません。
  • 推奨事項 — MCPサーバーの開発者はデバッグ出力をstderrに送ることを推奨します（stdoutは純粋なJSON-RPCメッセージのみにする）。
  • 既存サーバーへの影響 — v2.1.110へのアップデートにより、非JSON出力を持つ既存のMCPサーバーが正常に動作するようになります。

関連情報 ​