URL: https://gofastmcp.com/clients/fastmcp-remote
Title: fastmcp-remote - FastMCP

Documentation Index
Fetch the complete documentation index at:
/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Meet
Prefect Horizon
, the enterprise MCP gateway built by the team behind FastMCP
FastMCP
home page
v3
Prefect Horizon
PrefectHQ/fastmcp
25,596
PrefectHQ/fastmcp
25,596
Search...
Navigation
Clients
fastmcp-remote
Search the docs...
Ctrl
K
Documentation
Get Started
Welcome!
Installation
Quickstart
Servers
Overview
Core Components
Working with Tools
MCP Providers
Interactivity
Extensibility
Auth
Deployment
Apps
Overview
Quickstart
NEW
FastMCPApp
NEW
Interactive Tools
NEW
Generative UI
NEW
Custom HTML
Reference
Clients
Overview
Client-Only Package
Transports
fastmcp-remote
Operations
UPDATED
Authentication
UPDATED
Integrations
Auth
Web Frameworks
AI Assistants
AI SDKs
MCP.json
More
Settings
CLI
Upgrading
Development
What's New
FAQ
On this page
Installation
Host Configuration
Endpoint URLs and Connection Status
OAuth Storage
Options
Clients
fastmcp-remote
Copy page
Bridge remote MCP servers into stdio-only MCP hosts with uvx fastmcp-remote.
Copy page
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
"
]
}
}
}
​
Endpoint URLs and Connection Status
Pass the full MCP endpoint URL for the remote server. Many FastMCP HTTP servers expose MCP at
/mcp
, so a local development server may need
http://localhost:8000/mcp
rather than
http://localhost:8000
.
fastmcp-remote
starts a local stdio bridge, then connects to the upstream server when the MCP host initializes that bridge. If the upstream server is unavailable, the URL does not point to an MCP endpoint, or authentication cannot complete, initialization fails and the host should report the remote server as failed. After initialization succeeds, later tool, resource, prompt, and ping requests continue to proxy through the same remote server configuration.
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
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.
Client Transports
Previous
Calling Tools
Next
Ctrl
+I
discord
github
website
x
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform
Assistant
Responses are generated using AI and may contain mistakes.
\n\n
\n
\n \n
\n
