> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-1.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Bridge

> Relay local stdio and LAN HTTP MCP servers into your workspace over an outbound WebSocket.

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+**):

```bash theme={null}
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

```bash theme={null}
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:

```jsonc theme={null}
{
  "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.

<Tip>
  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.
</Tip>

## 3. Run

```bash theme={null}
mcp1-bridge run          # foreground
```

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

```bash theme={null}
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.