Bridge

The bridge relays a machine’s local MCP servers — both stdio (spawned subprocesses) and local/LAN HTTP servers — up to your mcp1 workspace over a single outbound WebSocket. Because it dials out, it works on laptops and dev boxes behind NAT with no public IP, port forwarding, or tunnel required. The gateway drives MCP end to end (initialize / tools/list / tools/call) through the tunnel; the bridge itself is a transparent pipe and never speaks MCP directly. Each relayed server becomes one transport=BRIDGE backend in your workspace, with its tools namespaced as namespace.tool.

Install

The bridge ships as a single self-contained file straight from your mcp1 server — no npm registry needed. On the target machine (needs Node.js 18+):

curl -fsSL https://api.mcp-1.dev/bridge/install.sh | sh

This drops an mcp1-bridge executable into ~/.local/bin. Prefer not to pipe to a shell? Download https://api.mcp-1.dev/bridge/cli.cjs, chmod +x it, and run it with Node directly.

1. Mint a bridge token

In the dashboard, go to Bridges → New bridge. Copy the mcp1brg_… token (shown once) and the WebSocket URL, for example wss://api.mcp-1.dev/bridge.

2. Configure

mcp1-bridge init --server wss://api.mcp-1.dev/bridge --token mcp1brg_xxx --import

--import pulls in the stdio and http MCP servers already defined in your Claude Code (~/.claude.json, ./.mcp.json) and Codex (~/.codex/config.toml) configs. Or edit ~/.mcp1-bridge/config.json directly:

{
  "serverUrl": "wss://api.mcp-1.dev/bridge",
  "token": "mcp1brg_xxx",
  "servers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me"] },
    "local_http": { "url": "http://127.0.0.1:9000/mcp", "headers": { "X-Api-Key": "…" } }
  }
}

Each key is the namespace (must match ^[a-z][a-z0-9_-]*$) and becomes the tool prefix. Entries are either {command, args?, env?} for stdio servers or {url, headers?} for HTTP servers.

Prefer not to hand-edit JSON? mcp1-bridge config opens an interactive editor (arrow keys + Enter) for the connection settings and server list, and validates before writing the file.

3. Run

mcp1-bridge run          # foreground

Or install it as a systemd --user service so it runs on login:

mcp1-bridge install
systemctl --user daemon-reload
systemctl --user enable --now mcp1-bridge
journalctl --user -u mcp1-bridge -f

Run loginctl enable-linger $USER to keep the service running after you log out.

Commands

Command	What it does
`init`	Scaffold the config (`--import` to pull from Claude/Codex configs).
`config`	Interactively edit the config (connection settings + servers).
`run`	Connect and relay (foreground).
`install`	Write a systemd `--user` unit.
`status`	Print the current config and configured servers.
`endpoint show`	Print this bridge’s gateway endpoint and relayed-server count.

Env overrides: MCP1_BRIDGE_CONFIG, MCP1_BRIDGE_SERVER_URL, MCP1_BRIDGE_TOKEN.

Notes

The bridge reconnects automatically with backoff; crashed stdio children are restarted, and the gateway rediscovers them on its next health poll.
Removing the bridge from the dashboard drops the socket and removes its relayed servers and tools from the workspace.
The token is a workspace-scoped bearer credential — treat it like a password.

Essentials

Guides

Install

1. Mint a bridge token

2. Configure

3. Run

Commands

Notes

​Install

​1. Mint a bridge token

​2. Configure

​3. Run

​Commands

​Notes

Install

1. Mint a bridge token

2. Configure

3. Run

Commands

Notes