notionMCP

mcp-remote

Connect an MCP Client that only supports local (stdio) servers to a Remote MCP Server, with auth support:

Why is this necessary?

So far, the majority of MCP servers in the wild are installed locally, using the stdio transport. This has some benefits: both the client and the server can implicitly trust each other as the user has granted them both permission to run. Adding secrets like API keys can be done using environment variables and never leave your machine. And building on npx and uvx has allowed users to avoid explicit install steps, too.

But there's a reason most software that could be moved to the web did get moved to the web: it's so much easier to find and fix bugs & iterate on new features when you can push updates to all your users with a single deploy.

With the latest MCP Authorization specification, we now have a secure way of sharing our MCP servers with the world without running code on user's laptops. Or at least, you would, if all the popular MCP clients supported it yet. Most are stdio-only, and those that do support HTTP+SSE don't yet support the OAuth flows required.

That's where mcp-remote comes in. As soon as your chosen MCP client supports remote, authorized servers, you can remove it. Until that time, drop in this one liner and dress for the MCP clients you want!

Usage

All the most popular MCP clients (Claude Desktop, Cursor & Windsurf) use the following config format:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

Custom Headers

To bypass authentication, or to emit custom headers on all requests to your remote server, pass --header CLI arguments:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

Note: Cursor, Codex-Cli and Claude Desktop (Windows) have a bug where spaces inside args aren't escaped when it invokes npx, which ends up mangling these values. You can work around it using:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
  }
},

To keep a credential out of the process arguments — where any other user on the machine can read it from the process list — put the headers in a file instead and pass --header-file. One Name: value per line; # starts a comment.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header-file",
        "/path/to/headers.txt"
      ]

# credentials for the example server
Authorization: Bearer my-token
X-Custom-Header: custom-value

A file that cannot be read is an error rather than a warning, so a mistyped path fails immediately instead of sending the request unauthenticated.

Multiple Instances

To run multiple instances of the same remote server with different configurations (e.g., different Atlassian tenants), use the --resource flag to isolate OAuth sessions:

{
  "mcpServers": {
    "atlassian_tenant1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant1.atlassian.net/"
      ]
    },
    "atlassian_tenant2": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.atlassian.com/v1/sse",
        "--resource",
        "https://tenant2.atlassian.net/"
      ]
    }
  }
}

Each unique combination of server URL, resource, custom headers, and --authorize-param values will maintain separate OAuth sessions and token storage.

The --resource value is sent as the RFC 8707 resource indicator on the authorization, token and refresh requests alike, so they always agree.

Extra authorization parameters

Some authorization servers require parameters of their own on the authorize call. Pass each as --authorize-param key=value, repeating the flag as needed:

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/mcp",
        "--authorize-param",
        "access_type=offline",
        "--authorize-param",
        "prompt=consent"
      ]

Those two are what Google wants before it will part with a refresh token — it does not recognise the offline_access scope. Auth0 wants audience=https://your-api to issue a JWT rather than an opaque token. login_hint=user@example.com is also common.

These apply to the authorization request only. resource is the exception: RFC 8707 wants the same value on the token and refresh requests too, and only --resource puts it there. Parameters the flow derives per request — state, code_challenge, client_id, redirect_uri, response_type — are refused, because a value that disagrees with the real one surfaces as an opaque server error.

Changing these starts a new sign-in, since a parameter like audience decides which API the token is for and a token issued for one is not valid for another.

Some authorization servers reject the resource parameter outright — Microsoft Entra ID v2 answers AADSTS9010010, for example. Pass --disable-resource-parameter to omit it entirely:

{
  "mcpServers": {
    "entra-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/mcp",
        "--disable-resource-parameter"
      ]
    }
  }
}

Flags

• If npx is producing errors, consider adding -y as the first argument to auto-accept the installation of the mcp-remote package.

      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

• To force npx to always check for an updated version of mcp-remote, add the @latest flag:

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

• To change which port mcp-remote listens for an OAuth redirect, add an additional argument after the server URL. By default the port is derived from the server URL, so every server gets a stable port of its own somewhere in 3335-49150, and mcp-remote walks up to 8 ports from there if it finds one taken. A port you pass explicitly is used as-is: it implies a redirect_uri the authorization server has already been given, so mcp-remote fails rather than quietly moving to a different one. --static-oauth-client-info pins the port the same way, for the same reason.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

• To change which host mcp-remote registers as the OAuth callback URL (by default localhost), add the --host flag. An IPv6 address may be given with or without brackets; pair an IPv6 loopback address with --bind-host ::1, since the server listens on IPv4 loopback by default.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

• To change the address the OAuth callback server listens on (by default 127.0.0.1), add the --bind-host flag. In a container, use 0.0.0.0 so the browser's redirect reaches the published callback port; --host still sets the host in the callback URL, so it can stay localhost. With --bind-host ::1 the callback URL defaults to [::1] instead, because 127.0.0.1 does not reach a server listening only on IPv6 loopback, and localhost may resolve to it; pass --host to override that. An empty value is ignored, so the server keeps listening on loopback. Anything that can reach the port can send it a callback, so publish it on the host's loopback only, e.g. docker run -p 127.0.0.1:9696:9696 ….

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696",
        "--bind-host",
        "0.0.0.0"
      ]

• To change the path mcp-remote serves the OAuth callback on (by default /oauth/callback), add the --callback-path flag. The path must start with /, and /wait-for-auth is reserved.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--callback-path",
        "/custom/callback"
      ]

• To send the browser to your own completion page after a successful OAuth token exchange, add --auth-success-url. The registered callback URL, state, PKCE flow and credential cache stay unchanged. No code, state, issuer or tokens are appended to the completion URL. Without this flag, the existing completion page is unchanged.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-success-url",
        "https://app.example.com/cli-connected"
      ]

The destination must be HTTPS, or HTTP on loopback. For HTTP on a trusted private network, also pass --allow-http. URLs containing credentials, a query or a fragment are rejected. A failed or timed-out exchange shows an error on the callback page instead of redirecting. --auth-timeout also bounds this wait (30 seconds by default). The option applies to browser authentication in both binaries, including mid-session reauthorization; device-code and client-credentials authentication have no browser callback.

• To allow HTTP connections in trusted private networks, add the --allow-http flag. Note: This should only be used in secure private networks where traffic cannot be intercepted.

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

• To enable detailed debugging logs, add the --debug flag. This will write verbose logs to ~/.mcp-auth/{server_hash}_debug.log with timestamps and detailed information about the auth process, connections, and token refreshing.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

• To suppress default logs, add the --silent flag. This will prevent logs from being emitted, except in the case where --debug is also passed.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--silent"
      ]

• To enable an outbound HTTP(S) proxy for mcp-remote, add the --enable-proxy flag. When enabled, mcp-remote will use the proxy settings from common environment variables (for example HTTP_PROXY, HTTPS_PROXY, and NO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

• To ignore specific tools from the remote server, add the --ignore-tool flag. This will filter out tools matching the specified patterns from both tools/list responses and block tools/call requests. Supports wildcard patterns with *.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

You can specify multiple --ignore-tool flags to ignore different patterns. Examples:

• delete* - ignores all tools starting with "delete" (e.g., deleteTask, deleteUser)
• *account - ignores all tools ending with "account" (e.g., getAccount, updateAccount)
• exactTool - ignores only the tool named exactly "exactTool"