Content
# Claude Extension MCP Bridge
Bridge Claude's Chrome/Brave extension native host to an MCP server so Codex can call extension browser tools.
## What this supports
This bridge exposes the extension's browser tool API (navigate, page read, tabs, computer interactions, etc.).
It does **not** add all Claude product features to Codex. It only forwards what the extension native host exposes.
## Files
- `native-host-daemon.js`: Native Messaging host + bridge daemon.
- `mcp-server.js`: MCP stdio server.
- `bridge-common.js`: shared transport/tool definitions.
- `register-native-host.ps1`: register one host name for one browser.
- `install-bridge.ps1`: convenience installer (backs up upstream host and registers bridge).
- `unregister-native-host.ps1`: remove bridge registration and optionally restore upstream.
- `examples/codex-config.toml`: Codex MCP config snippet.
## Prereqs
- Windows with `node` installed (`node.exe` in PATH or pass `-NodePath`).
- Claude extension installed (`fcoeoabgfenejglbffodgkkbkcdhcgfn` by default).
- Codex installed.
## Install (Windows PowerShell)
Run once per browser/profile (or again after reinstalling extension/browser).
From this project folder:
```powershell
cd C:\path\to\codex-browser
.\install-bridge.ps1 -Browser brave -HostMode both -Force
```
Or one line:
```powershell
cd C:\path\to\codex-browser; .\install-bridge.ps1 -Browser brave -HostMode both -Force
```
For Chrome, replace `-Browser brave` with `-Browser chrome`.
Notes:
- `HostMode both` registers both host names:
- `com.anthropic.claude_browser_extension`
- `com.anthropic.claude_code_browser_extension`
- Installer backs up existing host manifest to:
- `%LOCALAPPDATA%\ClaudeExtMcpBridge\<host>.upstream.json`
## Codex MCP config
Add this to `~/.codex/config.toml` (or use `examples/codex-config.toml`):
```toml
[mcp_servers.claude-ext-bridge]
command = "C:\\Program Files\\nodejs\\node.exe"
args = ["C:\\path\\to\\codex-browser\\mcp-server.js"]
startup_timeout_sec = 45
```
Why Windows Node: the extension native host runs on Windows; using Windows Node avoids WSL<->Windows localhost edge cases.
## Verify
1. Restart the browser after install.
2. In Codex, call:
- `bridge_status`
- `tabs_context_mcp` (or `tabs_context_mcp` with `createIfEmpty: true`)
- `navigate` with `tabId`/`tabGroupId` from context if needed.
3. If daemon is down, MCP auto-opens `https://clau.de/chrome/reconnect` and retries.
`bridge_status` should eventually show `extensionConnected: true`.
Opening the extension sidepanel is a manual fallback. Normal operation should reconnect without opening it every session.
## Uninstall / rollback
Remove registration:
```powershell
.\unregister-native-host.ps1 -Browser brave -HostName com.anthropic.claude_browser_extension
.\unregister-native-host.ps1 -Browser brave -HostName com.anthropic.claude_code_browser_extension
```
Restore upstream backup:
```powershell
.\unregister-native-host.ps1 -Browser brave -HostName com.anthropic.claude_browser_extension -RestoreUpstream
.\unregister-native-host.ps1 -Browser brave -HostName com.anthropic.claude_code_browser_extension -RestoreUpstream
```
## Troubleshooting
- `timed out` from extension test:
- native host wrapper is writing extra stdout (must write only framed native messages).
- `ECONNREFUSED ...:48765`:
- native host process not running, or wrong MCP command runtime.
- bridge retries multiple endpoints (`127.0.0.1`, `localhost`, WSL host IP) and auto-opens reconnect URL.
- `Extension is not connected. Open the Claude extension sidepanel first.`:
- wait a few seconds after browser startup for extension/native host handshake.
- if persistent, rerun `install-bridge.ps1` for the active browser (`brave` or `chrome`) and restart browser.
- auto-reconnect tuning:
- `CLAUDE_EXT_BRIDGE_AUTO_RECONNECT=0` to disable.
- `CLAUDE_EXT_BRIDGE_RECONNECT_URL` to override reconnect URL.
- `CLAUDE_EXT_BRIDGE_RECONNECT_COOLDOWN_MS` and `CLAUDE_EXT_BRIDGE_RECONNECT_RETRY_DELAY_MS` to tune timing.
- `No tab available`:
- call `tabs_context_mcp` first and pass returned `tabId`/`tabGroupId` to `navigate`.
## Security
This is a private-protocol bridge and may break with extension updates.
Review scripts before running on production machines.
