How mcpX works

mcpX separates the MCP connection from browser access. This keeps Chrome-facing permissions inside the extension and lets your AI client launch the server as a normal local MCP process.

Request flow

MCP-compatible AI client
        │ stdio
        ▼
local mcpX server
        │ authenticated loopback WebSocket
        ▼
Chrome extension
        │ on-demand browser APIs and page agent
        ▼
user-selected tab

1. Your AI client launches @rpx_/mcpx and calls an MCP tool.
2. The server validates and routes the request over an authenticated local connection.
3. The extension performs the browser-level or page-level operation.
4. The result returns through the server to your AI client.

The server correlates concurrent requests, timeouts, cancellation, disconnects, and typed extension responses.

Local discovery and pairing

The server binds to 127.0.0.1, prefers port 3000, and can use the first available port through 3010. The official extension checks local discovery endpoints, verifies the server handshake, and stores a pairing credential in Chrome-managed local storage.

Automatic pairing is limited to the official extension or an unpacked extension ID that you explicitly trust with MCPX_EXTENSION_ID.

Why mcpX uses a page agent

Chrome Manifest V3 service workers cannot directly read or interact with a page's DOM. mcpX injects a small page agent only when a DOM tool needs it and communicates through a Chrome runtime port.

Each tab session tracks its current document generation. Semantic references returned by snapshot include that generation, so an old reference cannot silently target a different element after navigation.

Browser APIs and debugger access

Navigation and tab tools use standard Chrome extension APIs. Screenshots and console monitoring require Chrome's debugger API:

• Console monitoring attaches only after console-start.
• Screenshots reuse a debugger session owned by mcpX.
• mcpX detaches only debugger sessions it attached.
• DevTools or another debugger can cause DEBUGGER_UNAVAILABLE.

For the data implications of each layer, read Security and privacy.