claude-code - 💡(How to fix) Fix ToolSearch fails to discover tools from a working custom stdio MCP server [1 comments, 2 participants]

Bug: ToolSearch cannot discover tools from a working stdio MCP server

Environment

• Claude Code CLI (macOS, Darwin 24.6.0)
• Model: claude-opus-4-6 (1M context)

Description

ToolSearch returns "No matching deferred tools found" for all tools exposed by a custom stdio-based MCP server, even though:

1. The server is correctly configured in ~/.claude/settings.json under mcpServers
2. The server binary exists and starts successfully
3. The server responds correctly to the MCP tools/list JSON-RPC method (verified manually via stdin/stdout)
4. The server lists 9 tools on stderr at startup

Steps to Reproduce

1. Configure a custom MCP server in ~/.claude/settings.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

1. Verify the server works manually:

MY_API_KEY=test node /path/to/dist/index.js
# stderr output: "my-mcp-server v1.0.0 running on stdio"
# stderr output: "Tools: tool_a, tool_b, tool_c, ..."

1. Send MCP initialize + tools/list via stdin — server responds correctly with all 9 tool definitions.

2. In a Claude Code session, try to discover the tools:

ToolSearch("tool_a")          → "No matching deferred tools found"
ToolSearch("+my-mcp")         → "No matching deferred tools found"
ToolSearch("select:tool_a")   → "No matching deferred tools found"

Multiple search strategies all fail — keyword, prefix match, exact select.

Expected Behavior

ToolSearch should index and return tools from all configured MCP servers that successfully start and respond to tools/list.

Actual Behavior

Tools from this specific MCP server are never indexed by ToolSearch. Other MCP servers in the same settings.json (e.g., a Gemini-based MCP server, Playwright plugin) work fine and their tools appear in ToolSearch and the deferred tools list in system-reminder.

Additional Context

• The server uses @modelcontextprotocol/sdk v1.6.1 with StdioServerTransport
• Built with TypeScript 5.9.3, compiled to JS via tsc
• The openai npm package (v4.96.0) is used internally as an HTTP client to a third-party API
• Node.js 18+
• This has persisted across multiple Claude Code sessions and full restarts
• The server emits a Node.js punycode deprecation warning ([DEP0040]) on startup — unclear if this interferes with tool registration or the MCP handshake
• The server has zod v3.23.8 as a dependency (used for input validation)
• No errors visible in the server's stderr output during Claude Code sessions

Workaround

Calling the underlying API directly via curl in Bash works but loses the MCP tool abstraction and requires manual JSON response parsing.

Questions

1. Is there a way to debug which MCP servers Claude Code successfully connects to and indexes?
2. Could the punycode deprecation warning on stderr interfere with the stdio JSON-RPC transport?
3. Is there a tool count or naming pattern limit that could cause silent drops?