Connecting a client to a remote MCP server with mcp-remote

The control gap

Several MCP clients still launch servers as local processes over stdio, while the servers worth protecting are remote and OAuth-protected. The mcp-remote bridge closes that gap: it runs locally, speaks stdio to the client, speaks Streamable HTTP to the server, and performs the OAuth flow in a browser. Most reported problems are not server bugs. They are cached credentials from an earlier attempt, or a config that hard-codes a bearer token and therefore never expires or revokes.

What good looks like

The client connects through a browser consent flow, the credential lives in the bridge's own store rather than in a config file, and revoking consent actually disconnects the client.

• Prefer the OAuth flow over a static header. A pasted token is a standing credential with no user attribution and no revocation path.
• Pin the bridge version in the config so an unattended update cannot change the auth behaviour under a working deployment.
• Clear the bridge's cached credential directory when a flow fails repeatedly, because a stale entry is the single most common cause.
• Keep the server's protected resource metadata correct, since the bridge relies on it to find the authorization server.

A production workflow

1. Add the bridge to the client's MCP configuration with the remote endpoint URL.
2. Start the client; the bridge opens a browser for consent on first connection.
3. The bridge stores the resulting credential locally and reuses it until it expires or is revoked.
4. Revoking consent server-side causes the next call to fail and the bridge to re-run the flow.

Copy this

This is the shape used by clients that read a JSON server list. The second block is the fix for the majority of authentication loops.

{
  "mcpServers": {
    "billing-tools": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://endram.com/mcp/billing-tools"]
    }
  }
}

# When the browser flow loops or the client reports an auth error,
# clear the bridge's cached credentials and reconnect:
rm -rf ~/.mcp-auth

# If you must use a static header instead of OAuth, know what you are accepting:
"args": ["-y", "mcp-remote", "https://host/mcp/slug",
         "--header", "Authorization: Bearer <token from your secret store>"]
# no user attribution, no consent record, no revocation short of rotating the token

Static headers are useful for a machine client in CI, where there is no human to consent and the credential is managed elsewhere. They are the wrong default for a person's laptop, because the audit trail then names a token rather than a user.

Evidence to require

• Which consents exist, for which client, user, and resource, with their expiry.
• Connections that authenticated with a static header rather than a user consent.
• Failed authorization attempts and whether they resolved after clearing cached credentials.
• Tool calls attributed to a named user rather than to a shared token.

Buyer checklist

• Are any client configs carrying a hard-coded bearer token, and who issued each one?
• Is the bridge version pinned, or resolved fresh on every launch?
• Does revoking a user's consent disconnect their client within one call?
• Do CI and desktop clients use different credential types, and is that visible in the log?