mcp-ferry

Some MCP servers only speak stdio. They run as a subprocess on your machine
because they read local data: your notes, your messages, your files. That's
fine when the MCP client runs on the same machine. It falls apart the moment
you want that tool from your phone, a browser, or an assistant running
somewhere else. The server has to sit next to the data; the client usually
doesn't.

mcp-ferry is the bridge between them. It puts a local stdio MCP server behind
a public, authenticated HTTPS URL, so any remote client can reach it while the
server keeps running right next to your data. One Cloudflare tunnel fronts as
many MCPs as you want, and adding another is one config block: no new tunnel,
no new sign-in.

How it works

MCP client ──HTTPS──► Cloudflare Edge ──Tunnel──► your machine
                          │                          │
                    Managed OAuth +              mcp-ferry HTTP server
                    Google sign-in              ├── /bear ──► bearcli mcp-server (stdio)
                                                ├── /things ► things-mcp       (stdio)
                                                └── /…

• mcp-ferry runs an HTTP server (Streamable HTTP transport) on localhost.
• Each /<path> proxies JSON-RPC frames to one long-lived stdio MCP subprocess.
• Ferry initializes each subprocess once and reuses its negotiated version and
  capabilities for subsequent client connections. After a subprocess restart,
  ferry repeats the handshake before forwarding the next request.
• A cloudflared Named Tunnel exposes that local server at https://<hostname>.
• Cloudflare Access protects the hostname with Managed OAuth: Cloudflare
  acts as a full OAuth 2.1 authorization server (PKCE + RFC 7591 dynamic client
  registration), so a remote MCP client can discover and authenticate on its own,
  with no manually-registered client credentials.
• Google is the identity provider behind Access; only the emails you allow can
  sign in.

Any MCP client that supports remote servers over HTTP with OAuth works. Nothing
here is client-specific.

Alternatives considered

mcp-ferry didn't start from scratch. The first plan was to take an existing
stdio-to-HTTP proxy and bolt the rest on by hand. Three projects are worth
knowing, and each is the better choice for a job mcp-ferry isn't trying to do:

• mcp-proxy (Python) is a clean,
  focused stdio↔Streamable HTTP/SSE bridge. If you want just the transport
  shim and you'll handle exposure and auth yourself, it's the leanest option.
• supergateway (Node) does the
  same job in the Node ecosystem and adds WebSocket transport. Reach for it if
  your tooling is Node or you need WS.
• mcp-remote goes the other direction:
  it lets a stdio-only client talk to an already-remote server. Different
  problem, and the right answer when that's the one you have.

All three are good at the transport. None of them do the rest: a public
hostname, Cloudflare Access with Managed OAuth so remote clients authenticate
without a pre-registered client, several MCPs behind one tunnel, a launchd
service so it survives a reboot, and a wizard that provisions the Cloudflare
side idempotently. mcp-ferry is those pieces assembled and hardened, not a
faster proxy. If you only need stdio↔HTTP, use one of the above. If you want
"expose a local MCP to the internet, behind Google sign-in, in a few
commands," that's the gap this fills.

Install

Requires Python 3.14+.

uv tool install mcp-ferry          # or: pipx install mcp-ferry

From source (for development):

git clone https://github.com/dalberto/mcp-ferry
cd mcp-ferry
uv tool install .                  # or: pipx install .

Setup

Prerequisite: the domain you'll use must already be an active Cloudflare
zone in the account your API token belongs to: the registrable apex
(e.g. example.com, covering bridge.example.com) added to Cloudflare with its
nameservers delegated and the zone Active. ferry setup creates a DNS record
inside an existing zone; it does not add a site to Cloudflare or change
registrar nameservers. If your domain isn't on Cloudflare yet: add the site in
the Cloudflare dashboard → point your registrar's nameservers at Cloudflare →
wait for the zone to go Active, then run the wizard. There is no
Cloudflare-assigned-domain fallback that preserves authentication. See
Why a domain is required.

Four steps: scaffold the config, get two credentials manually, then run the
wizard. Everything else is provisioned by ferry setup.

1. Create and edit the config

ferry init                      # writes ~/.config/mcp-ferry/config.toml
$EDITOR ~/.config/mcp-ferry/config.toml

Set bridge.hostname, cloudflare.tunnel_name, and at least one [[mcps]]
block. The hostname you pick here is referenced in step 3.

2. Cloudflare API token

1. Open https://dash.cloudflare.com/profile/api-tokens.
2. Click Create Token → Create Custom Token.
3. Give it a name like mcp-ferry.
4. Add these permissions:
   • Account ▸ Cloudflare Tunnel ▸ Edit
   • Account ▸ Access: Apps and Policies ▸ Edit
   • Account ▸ Access: Identity Providers ▸ Edit
   • Zone ▸ DNS ▸ Edit
   • Account ▸ Account Settings ▸ Read: only needed if you let the
     wizard auto-discover your account. Skip it if you pass --account-id
     (see below); without it and without --account-id, setup fails with
     "no Cloudflare accounts visible to this token".
5. Account resources: include your account.
6. Zone resources: include the specific zone hosting your hostname.
7. Create the token and copy it. Treat it like a password.

To run with the minimal token (just the four Edit permissions, no
Account Settings: Read), tell the wizard the IDs explicitly instead of having
it discover them. Get them from the Cloudflare dashboard: the account id is in
the dashboard URL; the zone id is on the zone's Overview page. Then either
put them in config.toml:

[cloudflare]
tunnel_name = "mcp-ferry"
account_id = "<account-id>"
zone_id = "<zone-id>"

or pass them per-run (also honored via CLOUDFLARE_ACCOUNT_ID /
CLOUDFLARE_ZONE_ID):

ferry setup --account-id <account-id> --zone-id <zone-id> --email [email protected]

Precedence is flag/env → config.toml → SDK discovery, so the auto-discovery
path still works unchanged if you'd rather not bother.

3. Google OAuth client

The Access identity provider needs a Google OAuth client ID + secret.

1. Open https://console.cloud.google.com/ and create a project (or reuse one).

2. APIs & Services ▸ OAuth consent screen:

   • User type: External.
   • Fill in app name, support email, developer contact email.
   • You can leave the scopes / test-users sections at their defaults.

3. APIs & Services ▸ Credentials ▸ Create Credentials ▸ OAuth client ID:

   • Application type: Web application.
   • Name: mcp-ferry (or anything).
   • Authorized redirect URIs: add exactly
     https://<your-team>.cloudflareaccess.com/cdn-cgi/access/callback.

   Find <your-team> in the Cloudflare Zero Trust dashboard at
   Settings ▸ Custom Pages ▸ team domain. (If you've never used Zero
   Trust on this account, the dashboard will prompt you to pick the team slug.)

4. Click Create and copy the Client ID and Client secret.

4. Run the wizard

ferry setup --email [email protected]

Allow more than one person by repeating --email or comma-separating:

ferry setup --email [email protected] --email [email protected]
ferry setup --email "[email protected], [email protected]"

The wizard:

• prompts for the Cloudflare API token (or reads CLOUDFLARE_API_TOKEN)
• prompts for the Google client ID + secret
• creates the tunnel, writes credentials to ~/.cloudflared/<tunnel-id>.json
• creates a CNAME for your hostname pointing at the tunnel
• creates the Google identity provider in Cloudflare Access
• creates the Access application with Managed OAuth enabled
• creates a single allow-list policy for the emails you passed
• updates config.toml to point cloudflare.credentials_file at the new file

The wizard is idempotent. Re-running with the same inputs is a no-op.

The allow-list is declarative. There is one policy (mcp-ferry allow-list)
and the --email flags are the source of truth: each ferry setup run rewrites
its include rules to exactly the emails you pass. Add or remove someone by
re-running with the new flag set. Do not hand-edit this policy in the
Cloudflare dashboard, because the next run overwrites it. (Other policies on the
app are left untouched; only mcp-ferry allow-list is managed.)

Connect a client

The bridge must be running first (ferry run, or ferry install for a
LaunchAgent). Cloudflare Access + OAuth live at the edge, so sign-in can
appear to succeed even when the bridge is down, but the MCP session then
fails because there's no origin behind the tunnel. Confirm it's up with the
checks in Verifying the server before debugging the
client.

In your MCP client, add a remote/HTTP MCP server pointing at the MCP path,
not the bare host:

https://<your-hostname>/<mcp-path>      e.g. https://mcp-ferry.example.com/bear

The host root has no route and 404s; only the configured [[mcps]] paths and
/healthz exist. Pointing a client at the bare hostname breaks the connection
in confusing ways. The first connection redirects to Cloudflare Access → Google;
after that the session is reused. OAuth-capable clients self-register via dynamic
client registration, so there's no client ID to paste. That's what Managed OAuth
is for.

After any re-run of ferry setup (it reconciles the Access app + IdP), remove
and re-add the connector in your client so it re-discovers and re-registers.
A registration cached against an earlier provisioning is the usual cause of
"auth succeeds, then the session errors" (e.g. code: Field required).

Which clients work out of the box

Hosted clients send a fixed public callback URL, which Managed OAuth only
permits if it's in the app's allowed-redirect-URI list. ferry setup provisions
Claude and ChatGPT by default. CLI/editor clients use an ephemeral loopback
redirect, which the wizard always allows via the
allow_any_on_localhost/allow_any_on_loopback flags, so there's no per-client
config. That's why MCP Inspector works with zero setup.

If a hosted client's callback isn't in the list, Cloudflare rejects the
authorization with Redirect URI not allowed by application configuration
(and the client then reports a downstream code: Field required). Add it:

ferry setup --allowed-redirect-uri https://claude.ai/api/mcp/auth_callback \
            --allowed-redirect-uri https://some-other-host/oauth/callback

--allowed-redirect-uri is repeatable and replaces the default list (so
include the ones you still want). It can also live in config.toml:

[cloudflare]
allowed_redirect_uris = [
  "https://claude.ai/api/mcp/auth_callback",
  "https://chatgpt.com/connector_platform_oauth_redirect",
]

Precedence: --allowed-redirect-uri → config.toml → built-in defaults.

Note: newer ChatGPT generates a per-connector callback URL. The default
entry works for many setups, but if ChatGPT's connector screen shows a
different "Redirect" value, add that exact URL with --allowed-redirect-uri
and re-run ferry setup (the Access app is reconciled, so the new list takes
effect), then re-add the connector.

Verifying the server

Before blaming the client, prove the server itself is correct. These three
unauthenticated probes need no browser and pinpoint exactly where a break is:

H=https://<your-hostname>

# 1. MCP path must challenge with 401 + WWW-Authenticate (not 200, not 404):
curl -sS -i -X POST -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' "$H/<mcp-path>"

# 2. Protected-resource metadata (also names your real auth server):
curl -sS "$H/.well-known/oauth-protected-resource"

# 3. Authorization-server metadata (endpoints + DCR + PKCE support):
curl -sS "$H/.well-known/oauth-authorization-server" | python3 -m json.tool

Expected:

• Probe 1 → HTTP/2 401 with www-authenticate: Bearer ... resource_metadata=....
  200 means Access isn't protecting the host; 404 means wrong path or the
  bridge is down.
• Probe 2 → 200 JSON like
  {"resource":"https://...","authorization_servers":["https://<TEAM>.cloudflareaccess.com"]}.
  That <TEAM> value is the source of truth for your Google redirect URI.
  It must be https://<TEAM>.cloudflareaccess.com/cdn-cgi/access/callback
  exactly. Read it here; do not guess the team slug.
• Probe 3 → 200 JSON containing authorization_endpoint, token_endpoint,
  registration_endpoint, response_types_supported: ["code"], and
  code_challenge_methods_supported. If registration_endpoint is absent,
  Managed OAuth isn't enabled on the Access app.

End-to-end with MCP Inspector

The probes prove the server config; MCP Inspector proves the whole
authenticated path: dynamic client registration, the browser OAuth round trip,
and an actual initialize + tools/list. Crucially it's a fresh client with
its own registration, so it isolates server problems from a stale registration
cached in your real client (Claude, etc.).

npx @modelcontextprotocol/inspector

In the Inspector UI: set Transport to Streamable HTTP, URL to
https://<your-hostname>/<mcp-path> (include the path), then Connect. It
opens a browser for the Cloudflare Access → Google sign-in, completes the
code + PKCE exchange, and lists the MCP's tools.

Interpreting the result:

• Inspector connects and lists tools → the server is fully correct. Any
  failure in your real client is client-side: remove and re-add the connector so
  it re-runs discovery + registration against the current server.
• Inspector fails the same way → the break is server/Cloudflare side and now
  reproducible locally. Inspector shows each OAuth step (discovery, registration,
  authorize, token) and the exact error. Debug from whichever step fails.

This is the fastest way to answer "is it the server or the client?" Start
here whenever a client connects but the session misbehaves.

Auto-start at login

ferry install                   # installs and loads a LaunchAgent
ferry status                    # check it's running
ferry logs -f                   # tail the bridge log

Logs live at ~/Library/Logs/mcp-ferry/. To remove: ferry uninstall.

Adding more MCPs

Edit config.toml and append another [[mcps]] block:

[[mcps]]
name = "things"
path = "/things"
command = "uvx things-mcp"

Restart the bridge (launchctl kickstart -k gui/$UID/io.github.dalberto.mcp-ferry
or just ferry uninstall && ferry install). The new MCP appears at
https://<hostname>/things. No new tunnel, no new Access app needed.

Changing your hostname

If you edit bridge.hostname in config.toml and re-run ferry setup, the
tunnel is reused (it's matched by name) but the DNS record and the Access
application are matched by the old hostname, so the wizard creates a new
CNAME and a new Access app and leaves the old ones behind. Nothing breaks, but
you should clean up the orphans manually:

1. Cloudflare dashboard → DNS → delete the old CNAME for the previous hostname.
2. Zero Trust → Access → Applications → delete the old mcp-ferry (<old-host>)
   application.

The tunnel, IdP, and mcp-ferry allow-list policy are unaffected and don't need
recreating.

Why a domain is required

mcp-ferry's whole point is an authenticated public URL. Authentication comes
from Cloudflare Access + Managed OAuth, and Access can only be attached to a
hostname on a Cloudflare zone you control. There is no first-party
Cloudflare-assigned domain that supports this:

• Quick Tunnels (*.trycloudflare.com) need no domain or account, but they
  cannot carry Cloudflare Access: the URL is unauthenticated and anyone with it
  reaches your MCP. They're also ephemeral (a new random hostname every
  restart). That defeats the security model, so mcp-ferry doesn't use them.
• *.cfargotunnel.com is the tunnel's internal target, not a routable public
  hostname; you can't serve or protect an app on it.
• Cloudflare doesn't hand out free Access-capable subdomains of its own domains.

So the floor is: a domain you own, on Cloudflare's free tier. The cheapest path
is a ~$10/yr registration (any registrar, or Cloudflare Registrar at cost) added
as a zone. If you genuinely want an unauthenticated, throwaway tunnel for local
testing, run cloudflared tunnel --url http://localhost:<port> directly. That
is explicitly not what this tool is for, and there's deliberately no --quick
flag that would make it easy to expose your data with no auth.

Troubleshooting

• ferry status: LaunchAgent state + per-MCP health from /healthz.
• ferry logs -f: tail stdout. Pass --stream err for stderr.
• cloudflared not finding the tunnel: confirm cloudflare.credentials_file
  in config.toml points at the JSON file the wizard wrote.
• Access redirect loop: verify the Google authorized redirect URI is exactly
  https://<team>.cloudflareaccess.com/cdn-cgi/access/callback and that the
  Access app's allowed IdP is the one the wizard created.
• Someone can't get in: confirm their email is in the --email set you last ran
  ferry setup with; the allow-list is rewritten from those flags each run.
• Redirect URI not allowed by application configuration (in the OAuth callback
  URL), surfacing to the client as a downstream code: Field required: the
  hosted client's callback isn't in the app's allowed-redirect-URI list. This
  affects hosted clients only (Claude/ChatGPT/etc.); loopback clients like MCP
  Inspector are unaffected, so "Inspector works but Claude doesn't" is the
  signature. Fix: ferry setup --allowed-redirect-uri <the exact callback>
  (see Which clients work out of the box),
  then re-add the connector.
• code: Field required with no Redirect URI not allowed in the callback: the
  bridge is almost certainly not running, or the connector points at the
  bare host instead of the /<mcp-path>. Run the
  verification probes; if they pass, remove and re-add
  the connector to clear a stale registration.
• Google redirect_uri_mismatch: the Google client's authorized redirect URI
  does not match. Get the exact value from probe 2 above
  (https://<TEAM>.cloudflareaccess.com/cdn-cgi/access/callback), not your app
  hostname, and not a guessed slug. Google can take a few minutes to honor a
  newly added URI.
• Google invalid_client / "client secret is invalid": the secret in Cloudflare
  doesn't match Google. Verify no truncation/whitespace and that it's the
  secret, not the client ID. Pass it via --google-client-secret (or
  GOOGLE_CLIENT_SECRET) rather than the prompt; the hidden prompt is the most
  common source of a one-character paste truncation. Re-running ferry setup
  re-pushes it (the IdP is reconciled declaratively).
• Edited the source but the CLI doesn't reflect it (e.g. No such option):
  uv tool install snapshots the code. Reinstall, or install once with
  uv tool install --force --editable . so local edits are picked up live.