fastmcp.server.providers.proxy
ProxyProvider for proxying to remote MCP servers.
This module provides the ProxyProvider class that proxies components from
a remote MCP server via a client factory. It also provides proxy component
classes that forward execution to remote servers.
Functions
default_proxy_roots_handler
roots/list, and the proxy is that
backend’s client, so it relays the request onto its own front session. This
reaches the wire through the SDK session rather than a Context method:
ctx.list_roots() is not part of FastMCP’s server-authoring API, because
SEP-2577 removed server-initiated requests from the modern protocol. The
relay exists only for handshake-era interop on both legs.
default_proxy_sampling_handler
default_proxy_roots_handler: server-initiated sampling is not part of
FastMCP’s server-authoring API, and this path only ever runs when both legs
of the proxy speak the handshake era.
default_proxy_elicitation_handler
default_proxy_log_handler
default_proxy_progress_handler
Classes
ProxyInitializeMiddleware
Deprecated middleware for forwarding instructions during initialization.
Methods:
on_initialize
ProxyTool
A Tool that represents and executes a tool on a remote server.
Methods:
model_copy
from_mcp_tool
run
get_span_attributes
ProxyResource
A Resource that represents and reads a resource from a remote server.
Methods:
model_copy
from_mcp_resource
read
get_span_attributes
ProxyTemplate
A ResourceTemplate that represents and creates resources from a remote server template.
Methods:
model_copy
from_mcp_template
create_resource
get_span_attributes
ProxyPrompt
A Prompt that represents and renders a prompt from a remote server.
Methods:
model_copy
from_mcp_prompt
render
get_span_attributes
ProxyProvider
Provider that proxies to a remote MCP server via a client factory.
This provider fetches components from a remote server and returns Proxy*
component instances that forward execution to the remote server.
All components returned by this provider have task_config.mode=“forbidden”
because tasks cannot be executed through a proxy.
Component lists (tools, resources, templates, prompts) are cached so that
individual lookups (e.g. during call_tool) can resolve from the cache
instead of opening a new backend connection. The cache stores the
backend’s raw component metadata and is shared across all sessions;
per-session visibility and auth filtering are applied after cache lookup
by the server layer. The cache is refreshed whenever a list_* call
is made, and entries expire after cache_ttl seconds (default 300).
Set cache_ttl=0 to disable caching. Disabling is recommended for
backends whose component lists change dynamically.
Methods:
get_tool_by_hash
crm_save, and nothing named save was ever listed. Matching on
the identity carried in meta is what the identity is for.
A remote that mounts one app twice sends back two tools claiming one
identity, exactly as a local composition would. That is refused here
on the same terms AggregateProvider refuses it, so a duplicated
app is caught wherever it is composed rather than only nearby.
get_tasks
ProxyMetadataMiddleware
Forward optional server metadata from a ProxyProvider backend.
Instructions and namespaced metadata are forwarded with frontend values
taking precedence. Protocol versions, capabilities, cache policy, and result
type are never copied from the backend. identity controls whether server
identity remains the gateway’s or uses the backend’s when available.
Methods:
on_initialize
on_discover
FastMCPProxy
A FastMCP server that acts as a proxy to a remote MCP-compliant server.
This is a convenience wrapper that creates a FastMCP server with a
ProxyProvider. For more control, use FastMCP with add_provider(ProxyProvider(…)).
ProxyClient
A proxy client that forwards advanced interactions between a remote MCP server and the proxy’s connected clients.
Supports forwarding roots, sampling, elicitation, logging, and progress.
The default forwarding handlers must resolve the proxy’s request context so
they relay server-initiated requests (roots/sampling/elicitation) back to the
proxy’s own connected client, not to the upstream server they are talking to.
Under SDK v2 an in-memory backend runs in the same event loop as this client,
so a naive get_context() inside a handler can resolve to the backend’s
context and forward the request straight back to the backend — an infinite
loop. To avoid that, ProxyTool.run (and the other proxy components) stash
the proxy-side RequestContext in _proxy_rc_ref before each backend
call, and the handlers are wrapped to restore it before forwarding.
Methods:
new
StatefulProxyClient
A proxy client that provides a stateful client factory for the proxy server.
The stateful proxy client bound its copy to the server session.
And it will be disconnected when the session is exited.
This is useful to proxy a stateful mcp server such as the Playwright MCP server.
Note that it is essential to ensure that the proxy server itself is also stateful.
The base ProxyClient already installs the context-restoring handlers
(see its docstring); this subclass additionally caches one client per stable
Connection and forces disconnect when the connection is torn down.
Methods: