fastmcp/docs/clients/fastmcp-remote.mdx

---
title: fastmcp-remote
description: Bridge remote MCP servers into stdio-only MCP hosts with uvx fastmcp-remote.
icon: bridge
---

`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.

```json
{
  "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`](/cli/running).

The command shape follows the original [`mcp-remote`](https://github.com/geelen/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:

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

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

```bash
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:

```json
{
  "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:

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

Repeat `--header` to send multiple headers:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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:

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

## Options

| Option | Description |
| ------ | ----------- |
| `--transport` | Choose `http` or `sse`. Defaults to `http`. |
| `--header` | Add a header to upstream requests, for example `--header "Authorization: Bearer <token>"`. Values may contain colons. Quote headers whose values contain spaces. Use `${VAR}` to expand environment variables inside values. Repeat for multiple headers. |
| `--auth` | Choose `oauth` or `none`. The default uses OAuth unless an `Authorization` header is provided. |
| `--resource` | Isolate OAuth token storage for a named remote resource. |
| `--host` | Set the OAuth callback hostname. Defaults to `localhost`. |
| `--auth-timeout` | Set how long to wait for the OAuth callback. Defaults to 300 seconds. |
| `--ignore-tool` | Hide tools whose names match a glob pattern. Repeat for multiple patterns. |
| `--debug` | Enable debug logging. |
| `--silent` | Suppress non-critical logs. |