Claude Code CLI: tools intermittently empty despite Connected status (race condition)

[alexandrehsantos]

Description

When using @browsermcp/mcp v0.1.3 with Claude Code CLI (not Cursor/VS Code), the MCP server shows as "Connected" but exposes zero tools intermittently. The same configuration works sometimes and fails other times across different Claude Code sessions.

Environment

• Client: Claude Code CLI (terminal)
• OS: Ubuntu 24.04 (Linux 5.15)
• Node: v22.22.0
• @browsermcp/mcp: v0.1.3
• Chrome: installed with BrowserMCP extension active
• BrowserMCP Connector: installed and running without errors

Steps to Reproduce

1. Install browsermcp: claude mcp add browsermcp -s user -- npx -y @browsermcp/mcp@latest
2. Ensure Chrome extension is installed and connector app is running
3. Start Claude Code CLI (claude)
4. Run claude mcp list → shows browsermcp: ✓ Connected
5. Try to use any browsermcp tool → no tools available
6. Exit and restart Claude Code → sometimes tools appear, sometimes they don't

Diagnosis

Verified the full connection chain is working:

# WebSocket server is listening
$ ss -tlnp | grep 9009
LISTEN 0 511 *:9009 *:* users:(("node",pid=XXXX,fd=21))

# Chrome extension IS connected via WebSocket
$ ss -tnp | grep 9009
ESTAB 127.0.0.1:45382 127.0.0.1:9009 users:(("chrome",...))
ESTAB [::ffff:127.0.0.1]:9009 [::ffff:127.0.0.1]:45382 users:(("node",...))

• WebSocket server on port 9009: listening ✅
• Chrome extension connected to WebSocket: established ✅
• MCP stdio transport connected to Claude Code: connected ✅
• Tools returned by tools/list: empty ❌

Root Cause Hypothesis

Race condition during startup. Claude Code spawns the browsermcp process and immediately sends tools/list via the MCP protocol. The server needs time to:

1. Start the WebSocket server on port 9009
2. Wait for the Chrome extension to connect
3. Only then can it fully resolve tool availability

If Claude Code's tools/list request arrives before the Chrome extension WebSocket connection is established, the tools list may be returned empty (or the tool handlers can't function). Since Claude Code doesn't re-query tools/list after initial handshake, the tools remain unavailable for the entire session.

This explains the intermittent behavior — it depends on whether Chrome's WebSocket connection happens to complete before or after Claude Code's initial tools/list request.

Suggested Fix

1. Implement notifications/tools/list_changed: After the Chrome extension connects via WebSocket, emit an MCP notification so the client re-fetches the tools list.
2. Or: Block the tools/list response until the WebSocket connection is established (with a reasonable timeout), rather than returning an empty list.

Workaround

Currently the only workaround is restarting Claude Code until the timing works out.

Related Issues

• No tools available in Cursor #49 — No tools available in Cursor
• MCP Server Shows “0 Tools Enabled” in Cursor v1.1.6 Despite Extension and Config Setup #82 — 0 Tools Enabled in Cursor
• invoke error of mcp:list-tools #141 — invoke error of mcp:list-tools