MCP Server Returns InternalServerError on All JSON-RPC Calls Despite Healthy CDP Connection

[maceatwork]

Issue Type

Agent Issue

Operating System

macOS

Description of the bug

The BrowserOS MCP server binary returns InternalServerError on ALL JSON-RPC method calls (initialize, tools/list, etc.), even though the health endpoint reports cdpConnected: true. This prevents any MCP client (Hermes agent, Claude, etc.) from using BrowserOS tools.

Environment

• OS: macOS (Apple Silicon)
• BrowserOS: v0.46.0
• browseros-cli: v0.2.2
• MCP Client: Hermes agent (but reproducible with raw curl)
• Connection: HTTP to http://127.0.0.1:[port]/mcp

Expected Behavior

The MCP server should return a valid JSON-RPC response with server capabilities when calling initialize or tools/list methods.

Actual Behavior

All JSON-RPC method calls return InternalServerError, making the MCP server completely unusable despite appearing healthy.

Steps to Reproduce

1. Start BrowserOS app normally

2. Note the MCP servr port (changes on each restart - see related issue BrowserOS MCP server binds to random ports, settings show wrong port #199)

3. Verify health endpoint works:

   curl http://127.0.0.1:9200/health
   # Returns: {"status":"ok","cdpConnected":true,...}

4. Attempt to initialize MCP connection:

   curl -X POST http://127.0.0.1:9200/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

5. Result: Returns InternalServerError instead of valid JSON-RPC response

Screenshots / Videos

No response

BrowserOS Version

v0.46.0

Additional Context

Observed Pattern

1. BrowserOS starts successfully
2. Health endpoint reports cdpConnected: true
3. Any JSON-RPC call to /mcp endpoint immediately returns InternalServerError
4. Restarting BrowserOS does not fix the issue
5. Port number changes on each restart (9200, 9201, etc.) - see issue BrowserOS MCP server binds to random ports, settings show wrong port #199

Related Issues

• browseros_server MCP handler degrades to 503 after unhandled errors in handleGetRequest #395: MCP handler degrades to 503 after unhandled errors (similar root cause, but that issue occurs after hours of running; this happens immediately)
• BrowserOS MCP server binds to random ports, settings show wrong port #199: MCP server binds to random ports (confirmed - port changes on each restart)
• Built-in MCP server not working #144: Built-in MCP server not working (older issue, possibly related)
• Breaking Change in v0.46.0: browseros-cli v0.2.2 incompatible with new MCP tools (tool names changed) #1346: Breaking Change in v0.46.0: browseros-cli v0.2.2 incompatible with new MCP tools (tool names changed)

Error Details

• Health endpoint: ✅ Works (cdpConnected: true)
• MCP endpoint: ❌ Returns InternalServerError on ALL methods
• Tested methods: initialize, tools/list, and others
• Port behavior: Port changes on each restart

Workaround

None currently. The built-in browser tools work, but the MCP server is completely non-functional.

Additional Context

This appears to be a regression or different manifestation of issue #395. The key difference:

• browseros_server MCP handler degrades to 503 after unhandled errors in handleGetRequest #395: Server works initially, then degrades after accumulating unhandled errors

• This issue: Server never works - fails immediately on first connection

The health check shows CDP is connected, but the MCP layer cannot execute any commands. This suggests the server binary may have a bug in its JSON-RPC handler or initialization logic.

[maceatwork]

Update: Additional Findings from Hermes Agent Investigation

I've done further investigation with my Hermes agent and can confirm this is definitely a BrowserOS server-side bug, not a configuration issue.

✅ What We Verified

1. Configuration is CORRECT: The MCP server config points to the right URL (http://127.0.0.1:[port]/mcp)
2. CDP endpoint WORKS: Port 9016 (CDP) is fully functional - can list tabs, extract content
3. Health endpoint WORKS: Returns {"status":"ok","cdpConnected":true}
4. MCP endpoint FAILS: Returns InternalServerError on ALL JSON-RPC methods

🔍 Root Cause Analysis

The issue appears to be in the MCP server binary itself:

• CDP connection is established and healthy
• Health checks pass
• But the MCP JSON-RPC handler cannot process ANY requests
• This happens immediately on startup (not after degradation like browseros_server MCP handler degrades to 503 after unhandled errors in handleGetRequest #395)

📊 Test Results

# Health check - WORKS
curl http://127.0.0.1:9201/health
# {"status":"ok","cdpConnected":true}

# MCP initialize - FAILS
curl -X POST http://127.0.0.1:9201/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'
# Returns: InternalServerError

# CDP tab listing - WORKS
curl -s http://127.0.0.1:9016/json/list | jq '.[] | {id, title, url}'
# Successfully lists open tabs

🎯 Impact

This completely breaks MCP integration:

• Hermes agent cannot discover BrowserOS tools
• All MCP clients (Claude, etc.) are affected
• Only workaround is to use built-in browser tools or direct CDP access

🔗 Related Issues

• Breaking Change in v0.46.0: browseros-cli v0.2.2 incompatible with new MCP tools (tool names changed) #1346: browseros-cli v0.2.2 incompatible with v0.46.0 (tool names changed) - This suggests v0.46.0 introduced breaking changes that may have also broken the MCP server
• browseros_server MCP handler degrades to 503 after unhandled errors in handleGetRequest #395: Similar MCP handler issues, but that degrades over time; this fails immediately

💡 Possible Cause

Given that v0.46.0 also broke browseros-cli (#1346), it's likely that the MCP server binary had breaking changes in v0.46.0 that weren't properly tested or documented.

🚧 Workaround

Currently using direct CDP connection (port 9016) and built-in browser tools as a workaround, but proper MCP integration is needed for full functionality.

---

Environment: macOS (Apple Silicon), BrowserOS v0.46.0, Hermes agent