fastmcp-remote

fastmcp-remote is FastMCP's standalone stdio bridge for remote MCP servers. Use it when an MCP host expects to launch a local command, but the server you want to use is hosted over Streamable HTTP or SSE.

{
  "mcpServers": {
    "linear": {
      "command": "uvx",
      "args": ["fastmcp-remote", "https://mcp.linear.app/mcp"]
    }
  }
}

The package is powered by FastMCP. It builds one FastMCP client for the remote URL, exposes that client as a local stdio proxy, and keeps the executable focused on that bridge. For running Python server files, local project environments, FastMCP config files, and development reload loops, use fastmcp run.

The command shape follows the original mcp-remote npm project, which established this stdio-to-remote bridge pattern for MCP hosts.

Installation

Most MCP hosts can run fastmcp-remote directly through uvx, so you usually do not need to install it yourself:

uvx fastmcp-remote https://example.com/mcp

If your host requires an already-installed command, install the package with your Python package manager:

uv tool install fastmcp-remote

Host Configuration

For hosts that use mcpServers JSON configuration, set the command to uvx and pass fastmcp-remote plus the remote server URL as arguments:

{
  "mcpServers": {
    "remote-api": {
      "command": "uvx",
      "args": ["fastmcp-remote", "https://example.com/mcp"]
    }
  }
}

OAuth is enabled automatically for HTTPS servers. The first connection opens the browser-based OAuth flow when the server requires authentication, then stores tokens locally for future runs.

To pass a bearer token or another custom header directly, provide --header in Name: Value form. The header name ends at the first colon, so values can contain additional colons. Quote the header when the value contains spaces, just like any other shell argument. An Authorization header disables OAuth by default:

{
  "mcpServers": {
    "private-api": {
      "command": "uvx",
      "args": [
        "fastmcp-remote",
        "https://example.com/mcp",
        "--header",
        "Authorization: Bearer <token>"
      ]
    }
  }
}

Repeat --header to send multiple headers:

uvx fastmcp-remote https://example.com/mcp \
  --header "Authorization: Bearer <token>" \
  --header "X-Workspace: production" \
  --header "X-Client-Name: My MCP Host" \
  --header "X-Callback-Url: https://example.com/oauth/callback"

Some MCP hosts on Windows have trouble preserving spaces inside command arguments. Put the spaced value in an environment variable and reference it from the header value:

{
  "mcpServers": {
    "remote-api": {
      "command": "uvx",
      "args": [
        "fastmcp-remote",
        "https://example.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <token>"
      }
    }
  }
}

For local development servers over plain HTTP, disable OAuth when the server is unauthenticated:

uvx fastmcp-remote http://localhost:8000/mcp --auth none

OAuth Storage

OAuth tokens are stored under ~/.fastmcp/remote by default. Set FASTMCP_REMOTE_CONFIG_DIR to use another directory:

FASTMCP_REMOTE_CONFIG_DIR=~/.config/fastmcp-remote uvx fastmcp-remote https://example.com/mcp

Use --resource to isolate tokens for a particular remote server identity:

uvx fastmcp-remote https://example.com/mcp --resource example-prod

If the remote authorization server requires a fixed callback port or hostname, pass them after the URL:

uvx fastmcp-remote https://example.com/mcp 3334 --host 127.0.0.1

Options