Skip to main content
Glama
mcp-mesh-bridge
by invinite-fi
README.md
# mcp-mesh-bridge

A Claude Desktop extension that reaches an MCP server on a private network, such as a VPN or a
mesh, and signs you in with OAuth.

## Why

Claude Desktop's connectors call MCP servers from Anthropic's cloud. A server that only your VPN
or mesh can reach is out of their reach.

This bridge runs on your own machine instead. Claude Desktop starts it as a local MCP server. It
passes every message on to the server's streamable-HTTP endpoint, unchanged, and passes the answers
back. Your machine is on the private network, so the server is in reach.

The bridge knows no domain tools of its own: whatever the server offers, Claude sees. When a
server offers `start_upload` for single-use direct HTTP PUT uploads, the bridge automatically adds
`upload_local_file` so Claude Desktop can stream a local file from disk (via the native OS file
picker or an explicit path) straight to that server without passing file bytes through the chat.

## Uploading local files

A server that wants local files offers a tool named `start_upload` that takes a string `filename`
and a numeric `bytes`. The bridge then adds `upload_local_file`, unless the server has a tool of
that name itself. A `start_upload` of other arguments gets none, as it is for something else. A
server may also say so outright, whatever its schema, in the tool's `_meta`:
`"fi.invinite/mcp-mesh-bridge-upload": {"version": 1}`; another version gets none. When the server
says its tools changed (`notifications/tools/list_changed`), the bridge looks again. It takes `path` (or opens
the system's file picker without one) and every argument of `start_upload` but `filename` and
`bytes`, which the bridge fills in from the file. It passes those arguments on as Claude gives them.

1. The bridge calls `start_upload` with `filename` (the file's name, without its folder), `bytes`
   (its size) and the other arguments.
2. The result names `upload_id` and `upload_url`, in `structuredContent`, as a JSON text, or as
   `upload_id: …` and `upload_url: …` lines of text.
3. The bridge sends the whole file in one `PUT` to `upload_url`, with `Content-Length` and
   `application/octet-stream`. The URL must be on the server URL's own origin, and the bridge
   follows no redirect. The URL should work once and carry its own credential, as the bridge sends
   no sign-in with it.
4. A 2xx answer means the file arrived. A JSON answer may say `{"state": "failed", "error": "…"}`,
   which the bridge reports.
5. The bridge gives Claude the `upload_id` and what to do with the upload next: `next` from
   `structuredContent` if the server gives it, else the rest of what `start_upload` said, without
   its URL.

## Install

Download the `.mcpb` file from the [latest release](https://github.com/invinite-fi/mcp-mesh-bridge/releases/latest)
and open it. Claude Desktop asks for the server's URL, then installs the extension.

In a Claude Team or Enterprise organisation, an owner can upload the `.mcpb` to the organisation's
allowlist: **Organization settings → Connectors → Desktop**. People then install it from inside
Claude Desktop.

It runs on macOS and Windows. Claude Desktop brings the Node.js it needs.

## Configure

| Setting       | What it is                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------------- |
| Server URL    | The server's streamable-HTTP address, such as `https://mcp.example.internal/mcp`. Required.    |
| Sign-in port  | The port on your machine the browser returns to after signing in. Empty: one chosen per URL.   |
| Client ID     | Only for a server that does not let clients register themselves: the client registered for it. |
| Client secret | Only if that client has a secret. Claude Desktop keeps it in your system's keychain.           |

## Signing in

The first time Claude uses the server, the bridge opens your browser at the server's sign-in. When
you are done, the browser returns to `http://127.0.0.1:<port>/callback` on your own machine, and the
bridge takes over from there.

The bridge finds the server's sign-in itself (OAuth protected resource and authorization server
metadata), registers itself as a client if the server allows it, and uses PKCE. It refreshes the
access token when it expires, so you sign in again only when the server asks you to.

The server must accept a loopback redirect URI (`http://127.0.0.1:<port>/callback`). Most servers
built for MCP clients do.

What the server gives the bridge, its client registration and tokens, is kept per server URL:

- **macOS:** in `~/Library/Application Support/mcp-mesh-bridge/`, encrypted with AES-256-GCM. The
  key is in your login Keychain, under the service name `mcp-mesh-bridge`.
- **Windows:** in `%APPDATA%\mcp-mesh-bridge\`, encrypted with Windows' data protection for your
  user account.
- **Elsewhere:** in `~/.config/mcp-mesh-bridge/`.

Only your user can read these folders and files. The bridge writes a file whole or not at all.

If a stored sign-in can't be read, the bridge says so on stderr and signs you in again.

## Signing out

Forget a server's sign-in with:

```sh
node server/index.mjs https://mcp.example.internal/mcp --logout
```

Run it from the extension's folder, or use `node build/src/main.js` from a clone of this repository.

If the server offers token revocation, the bridge asks it to revoke the sign-in first. It asks only
the sign-in server that issued it, at that server's own address. It then says whether anything was
stored. A bridge still running doesn't store the sign-in again.

## Command line

The bridge also runs outside Claude Desktop:

```text
mcp-mesh-bridge <server-url> [--port <n>] [--client-id <id>] [--login | --logout]
```

- With no option, it relays on stdin and stdout, as Claude Desktop runs it.
- `--login` signs in now and exits.
- `--logout` forgets the server's sign-in and exits.

It writes its own messages to stderr only. Stdout carries MCP.

## A branded build

An organisation can build its own copy, with its own name and its server's URL built in. It asks
nothing at install; the sign-in port is chosen from the URL.

```sh
yarn install --immutable
yarn bundle:branded --name "Example Knowledge" --url https://mcp.example.internal/mcp \
  --icon icon.png --out dist/example-knowledge.mcpb
```

`--icon` is a square PNG, 512 px is plenty. It has to read on light and dark themes alike: Claude's
organisation allowlist accepts only one icon, as it refuses a manifest with themed `icons`. A logo
that would vanish on one theme can sit on a tile of its own colour.

Upload that file to your organisation's allowlist. Keep it out of this repository and its releases:
it names your private server.

## Security

- The bridge listens only on `127.0.0.1`, and only while a sign-in is under way.
- It sends nothing anywhere but the server you configure and that server's sign-in.
- It never writes a token to a log, and keeps no secret on a command line.
- It has one runtime dependency, the official MCP TypeScript SDK, bundled into the extension.

**The browser and file picker.** The bridge opens a sign-in address only if it is `https:`. It also
opens `http:` when the address is on your own machine, or when the server URL is `http:` itself. It
logs where the sign-in is. It starts the browser and the native file picker with fixed system
programs: `/usr/bin/open` and `/usr/bin/osascript` on macOS, `rundll32.exe` and Windows PowerShell
from `System32` on Windows, or `xdg-open` / `zenity` / `kdialog` from a system folder on Linux. It
never runs a program found on `PATH`. `upload_local_file` only streams to the configured server's
own origin, never follows redirects, and never writes upload URLs or tokens to a log.

**What the Keychain protects.** On macOS the key is a Keychain item that `/usr/bin/security`
created. Any program running as you can read it with that same tool, without asking you. So the
Keychain protects the stored sign-in only from a copy of the file taken elsewhere, such as a backup.
Windows' data protection is the same: any program running as you can decrypt the file.

**Plain http.** An `http:` server URL that isn't on your own machine gets a warning on stderr. The
bridge still allows it, since a mesh network encrypts the traffic itself. Use `https:` anywhere
else.

**Limits.** The bridge refuses an answer over 32 MB, or one event over 32 MB in a stream. It cuts
what the server says to 2 KB before it reaches a log or Claude.

**Releases.** The `.mcpb` in a release isn't signed yet. Signing comes later.

## Development

```sh
yarn install --immutable
yarn validate   # typecheck, lint, format check, tests
yarn bundle     # dist/mcp-mesh-bridge-<version>.mcpb
```

Yarn is vendored in `.yarn/releases`: any installed Yarn runs that version, and without one,
`node .yarn/releases/yarn-*.cjs` does. Dependencies run no install scripts.

A `v*` tag that matches `manifest.json`'s version publishes the `.mcpb` as a GitHub release.

## License

MIT. Copyright Invinite Oy.