# mcp-bridge (`mcpb`)

A local **stdio MCP Server** that bridges any remote **Streamable HTTP** MCP server to your MCP client (Claude Desktop, Cursor, VS Code, WorkBuddy, …) with zero changes to the remote side.

- **Transport normalization** — clients only need stdio support.
- **Network traversal** — optional outbound HTTP proxy for restricted/corporate networks.
- **Zero-change bridging** — the remote server needs no modification.

> CLI command: `mcpb`. Repo: `github.com/Slothtron/mcp-bridge`.

## Install

From GitHub (npm installs directly from the repo; the prebuilt binary is fetched from GitHub Releases at install time — no npm publish needed):

```bash
# MUST pin a tag that matches a GitHub Release (vX.Y.Z)
npm install github:Slothtron/mcp-bridge#v0.1.0
# or run without installing:
npx github:Slothtron/mcp-bridge#v0.1.0 --remote https://example.com/mcp
```

> Note: the installer downloads `mcpb-<os>-<arch>` from the GitHub Release matching this
> package's `version`. When installing from git, pin a tag (e.g. `#v0.1.0`); installing the
> default branch only works if its `package.json` version has a matching Release.

Via Go (no npm needed):

```bash
go install github.com/Slothtron/mcp-bridge@latest
```

## Usage

```bash
mcpb --remote https://example.com/mcp
mcpb --remote https://example.com/mcp --proxy http://corp-proxy:8080
mcpb --remote https://example.com/mcp --header "Authorization: Bearer <TOKEN>"
# Opt in to server-initiated list_changed via GET SSE (off by default):
mcpb --remote https://example.com/mcp --standalone-sse
```

### MCP Client config

```json
{
  "command": "mcpb",
  "args": [
    "--remote", "https://example.com/mcp",
    "--proxy", "http://corp-proxy:8080",
    "--header", "Authorization: Bearer <TOKEN>"
  ]
}
```

For `npx`, set `"command": "npx"` and `"args": ["github:Slothtron/mcp-bridge#v0.1.0", "--remote", "https://example.com/mcp"]`.

If secrets / proxy live in **mise** `[env]`, Cursor does **not** load them automatically for MCP child processes. Prefer wrapping with `mise x`:

```json
{
  "command": "mise",
  "args": [
    "x", "--",
    "mcpb",
    "--remote", "https://example.com/mcp",
    "--header", "Authorization: Bearer ${TOKEN}",
    "--proxy", "${HTTPS_PROXY}"
  ],
  "env": {},
  "type": "stdio"
}
```

Or keep `"command": "mcpb"` and put the variables in the MCP entry's `"env"` block, and ensure `mcpb` is on Cursor's `PATH`.

### Flags

| Flag | Required | Description | Default |
|---|---|---|---|
| `--remote` | yes | Remote Streamable HTTP MCP server URL | — |
| `--proxy` | no | Outbound HTTP proxy URL | `HTTP_PROXY` / `HTTPS_PROXY` |
| `--header` | no | Outbound request header (repeatable) | `MCPB_HEADERS` env |
| `--standalone-sse` | no | Enable remote standalone GET SSE (server-initiated `list_changed`) | off |
| `--max-retries` | no | Reconnect budget for the remote transport | `5` |

Header values support `${VAR}` placeholders resolved from the environment at runtime (fail-fast if unset).

Outbound HTTP uses a **15s response-header timeout** (not a total request timeout), so hanging peers fail faster without cutting off long tool-call response bodies.

Standalone GET SSE is **off by default**. Some gateways accept `initialize` but never return headers for the follow-up GET; leaving SSE on would block `mcpb` startup and surface as a client `MCP error -32001: Request timed out`. Enable `--standalone-sse` only when the remote correctly supports GET SSE and you need live `list_changed` pushes (startup still syncs tools/prompts/resources once).

### Troubleshooting

| Symptom | Likely cause | What to try |
|---|---|---|
| Client shows `MCP error -32001: Request timed out` and mcpb never logs `bridging remote … over stdio` | Startup blocked in remote Connect (historically: hanging GET SSE) | Upgrade mcpb (SSE off by default); check stderr; confirm proxy/remote with `curl` |
| `undefined environment variable(s): …` | `${VAR}` in args but var missing in the MCP process env | Inject via MCP `"env"`, or run under `mise x --` |
| `startup failed: connect to remote …` within ~15s | Proxy down, auth failure, or peer not returning headers | Fix proxy/token; inspect remote URL with the same headers |

See [`TECHNICAL_DESIGN.md`](./TECHNICAL_DESIGN.md) for the full design.