ToolSearch fails to discover tools from a working custom stdio MCP server
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:
- The server is correctly configured in
~/.claude/settings.jsonundermcpServers - The server binary exists and starts successfully
- The server responds correctly to the MCP
tools/listJSON-RPC method (verified manually via stdin/stdout) - The server lists 9 tools on stderr at startup
Steps to Reproduce
- 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": "..."
}
}
}
}
- 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, ..."
- Send MCP initialize + tools/list via stdin — server responds correctly with all 9 tool definitions.
- 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/sdkv1.6.1 withStdioServerTransport - Built with TypeScript 5.9.3, compiled to JS via
tsc - The
openainpm 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
punycodedeprecation warning ([DEP0040]) on startup — unclear if this interferes with tool registration or the MCP handshake - The server has
zodv3.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
- Is there a way to debug which MCP servers Claude Code successfully connects to and indexes?
- Could the
punycodedeprecation warning on stderr interfere with the stdio JSON-RPC transport? - Is there a tool count or naming pattern limit that could cause silent drops?
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗