Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

接続はできるが tools/list に失敗するMCPサーバーが、ツールを0件表示するだけで無音だった問題を修正しました。現在は一度リトライし、/mcp に「connected · tools fetch failed」を表示します。

原文（英語） ​

Fixed MCP servers that connect but fail tools/list silently showing 0 tools — they now retry once and show 'connected · tools fetch failed' in /mcp

概要 ​

MCPサーバーへの接続自体は成功するものの、ツール一覧の取得（tools/list）に失敗した場合、以前はツールが0件として表示されるだけで、ユーザーは問題が発生していることを把握できませんでした。この修正により、失敗した場合は自動的に1回リトライし、それでも失敗した場合は /mcp コマンドで「connected · tools fetch failed」という明確なエラー状態が表示されます。これにより、接続問題のデバッグが大幅に容易になります。

基本的な使い方 ​

MCPサーバーのツール取得に問題がある場合は、/mcp コマンドで状態を確認できます。

/mcp

# 正常な場合の表示例
# my-server: connected · 12 tools

# ツール取得に失敗した場合の表示例（修正後）
# my-server: connected · tools fetch failed

# 完全に接続できない場合
# my-server: failed

実践例 ​

MCPサーバーの状態確認 ​

# /mcpコマンドでMCPサーバーの状態を確認
/mcp

# 出力例
# MCPサーバー一覧:
# ✓ github-server: connected · 8 tools
# ✗ database-server: connected · tools fetch failed  ← ツール取得に失敗
# ✗ api-server: failed  ← 接続自体に失敗

tools fetch failedへの対処方法 ​

bash
# 1. MCPサーバーのログを確認
cat ~/.claude/logs/mcp-server.log

# 2. MCPサーバーを手動でテスト
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node my-mcp-server.js

# 3. MCPサーバーの設定を確認
cat ~/.claude/claude_desktop_config.json

# 4. MCPサーバーを再起動（Claude Codeを再起動）
# Ctrl+C でClaude Codeを終了して再起動
claude

MCPサーバーの実装でtools/listを正しく実装する ​

javascript
// MCPサーバーでtools/listを正しく実装する例
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "search",
        description: "検索を実行します",
        inputSchema: {
          type: "object",
          properties: {
            query: {
              type: "string",
              description: "検索クエリ"
            }
          },
          required: ["query"]
        }
      }
    ]
  };
});

// エラーハンドリングも適切に実装
server.setRequestHandler(ListToolsRequestSchema, async () => {
  try {
    const tools = await fetchToolsFromDatabase();
    return { tools };
  } catch (error) {
    // エラーをスローして失敗を明示
    throw new Error(`ツール一覧の取得に失敗しました: ${error.message}`);
  }
});

自動リトライの動作確認 ​

# Claude Codeを起動すると、MCPサーバーへの接続が試みられる
# 1. 初回接続でtools/listを実行
# 2. 失敗した場合、自動的に1回リトライ
# 3. リトライも失敗した場合、/mcpで「connected · tools fetch failed」と表示

# 状態確認
/mcp

注意点 ​

  • 「connected · tools fetch failed」は接続自体は成功しているが、ツール一覧の取得に失敗していることを示します。MCPサーバーのプロセス自体は動作しています。
  • リトライは自動的に1回行われます。手動でリトライするにはClaude Codeを再起動してください。
  • この問題はMCPサーバー側の実装の問題である場合が多いため、サーバーのログを確認して根本原因を特定することをお勧めします。
  • 「failed」（接続失敗）と「connected · tools fetch failed」（ツール取得失敗）は異なる状態です。対処方法が異なるため、メッセージを確認してください。

関連情報 ​