How to Debug the Vibium MCP Server

You debug the Vibium MCP server by isolating the layer that fails: run the server directly, send JSON-RPC by hand, list its tools, and check the browser launch — then read the error it returns. Vibium is AI-native browser automation on WebDriver BiDi, a single Go binary that auto-downloads Chrome for Testing and ships a built-in Model Context Protocol (MCP) server, created by Jason Huggins (co-creator of Selenium and Appium). Most MCP problems fall into three buckets: the server is not registered or discovered by the host, the server starts but Chrome will not launch, or a tool call sends bad arguments. Working from the server outward — npx -y vibium mcp first, then the host — tells you exactly where the break is. This guide walks each check with the exact commands, using only documented Vibium behavior.

How do you confirm the server even starts?

Run the MCP server directly in a terminal. A healthy server starts and waits silently for input on stdin:

npx -y vibium mcp

If you see it start and hang (waiting), it is alive — press Ctrl+C to exit. If it errors immediately, the message tells you what is wrong (a missing binary, a bad flag, or a download failure). This single check separates "the server is broken" from "my host config is broken," which is the most important fork in MCP debugging.

How do you test the server with raw JSON-RPC?

Send an initialize request and verify the handshake. This proves the protocol layer works independently of any AI host:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' \
  | npx -y vibium mcp

You should get a JSON response containing serverInfo and capabilities. If that returns cleanly, list the tools to confirm the catalog is being advertised:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | npx -y vibium mcp | jq '.result.tools[].name'

A populated list means the server is fully functional and your agent should be able to see every tool. If the list is what you expect but the agent still cannot use the tools, the problem is in the host, not Vibium. The full catalog is documented in the Vibium MCP tools reference.

How do you run a real browser command end to end?

Drive a full session over stdin to confirm the server can actually launch and control Chrome. Send launch → navigate → quit as separate JSON-RPC lines:

cat << 'EOF' | npx -y vibium mcp
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"browser_launch","arguments":{"headless":false}}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_navigate","arguments":{"url":"https://example.com"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"browser_quit","arguments":{}}}
EOF

You should see one JSON result per line, ending with the session closing. If browser_launch is where it breaks, the issue is Chrome, not MCP — jump to the Chrome section below.

Why does the agent not see the tools after I add the server?

Tool discovery runs on startup, so a host that was already running will not pick up a newly added or changed server. After any change, start a new session, then confirm registration:

claude mcp list

A healthy entry shows the server connected, for example vibium: npx -y vibium mcp - ✓ Connected. If it is missing, re-add it:

claude mcp add vibium -- npx -y vibium mcp

This "must restart the session" rule trips up almost everyone once. See set up Vibium MCP in Claude Code for the full host setup, including Cursor in set up Vibium MCP in Cursor.

How do you fix Chrome failing to launch?

Chrome for Testing downloads automatically the first time a browser launches; if that download or launch fails, fetch it explicitly:

npx -y vibium install

On macOS, Gatekeeper can quarantine the bundled chromedriver. Clear the quarantine attribute:

xattr -cr "$(npx -y vibium which chromedriver)"

If Chrome still will not start, a lingering process from a previous crashed run is often the cause — see the next section.

How do you clear zombie Chrome and chromedriver processes?

If a previous run was killed mid-session, Chrome or chromedriver may still be holding ports, which blocks new launches. Find and stop them:

ps aux | grep -E 'chromedriver|Chrome for Testing' | grep -v grep

Kill any leftovers, then retry the server. A failed connection that mentions a refused WebSocket or a busy port almost always points to a zombie process. After clearing them, re-run the end-to-end test above to confirm launch works again.

How do you read and fix tool-call errors?

When a specific tool fails, read the error text in the JSON-RPC result — it names the problem. The most common cause is a missing or mistyped argument, since each tool enforces its inputSchema. Re-check the schema for that tool:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | npx -y vibium mcp | jq '.result.tools[] | select(.name=="browser_navigate")'

Compare your call's arguments against the schema's required fields and types. For element-targeting tools, a "not found" error usually means the selector is wrong — switch to a semantic match (role, text, label, testid) per find an element, or confirm the element exists with wait for an element.

A quick debugging checklist

Work top to bottom; stop at the first failure, because it is the real cause.

1. Server starts: npx -y vibium mcp hangs waiting (good).
2. Handshake works: initialize returns serverInfo.
3. Tools listed: tools/list returns the expected names.
4. Browser launches: the end-to-end stdin test reaches browser_quit.
5. Host sees it: claude mcp list shows connected (after a fresh session).
6. Tool args valid: failing call matches the tool's inputSchema.

If steps 1–4 pass but the agent still misbehaves, the issue is host config or prompt, not Vibium. If step 4 fails, it is Chrome (install, Gatekeeper, or zombies).

Next steps

• Vibium MCP tools reference
• Set up Vibium MCP in Claude Code
• Build an AI agent that browses the web
• Vibium glossary