mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-15 18:19:10 +02:00
111 lines
No EOL
4.8 KiB
Text
111 lines
No EOL
4.8 KiB
Text
---
|
|
title: Proxy Servers
|
|
sidebarTitle: Proxy Servers
|
|
description: Use FastMCP to act as an intermediary or change transport for other MCP servers.
|
|
icon: arrows-retweet
|
|
---
|
|
import { VersionBadge } from '/snippets/version-badge.mdx'
|
|
|
|
<VersionBadge version="2.0.0" />
|
|
|
|
FastMCP provides a powerful proxying capability that allows one FastMCP server instance to act as a frontend for another MCP server (which could be remote, running on a different transport, or even another FastMCP instance). This is achieved using the `FastMCP.as_proxy()` class method.
|
|
|
|
`as_proxy()` accepts either an existing `Client` or any argument that can be passed to a `Client` as its `transport` parameter—such as another `FastMCP` instance or a URL to a remote server.
|
|
|
|
## What is Proxying?
|
|
|
|
Proxying means setting up a FastMCP server that doesn't implement its own tools or resources directly. Instead, when it receives a request (like `tools/call` or `resources/read`), it forwards that request to a *backend* MCP server, receives the response, and then relays that response back to the original client.
|
|
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant ClientApp as Your Client (e.g., Claude Desktop)
|
|
participant FastMCPProxy as FastMCP Proxy Server
|
|
participant BackendServer as Backend MCP Server (e.g., remote SSE)
|
|
|
|
ClientApp->>FastMCPProxy: MCP Request (e.g. stdio)
|
|
Note over FastMCPProxy, BackendServer: Proxy forwards the request
|
|
FastMCPProxy->>BackendServer: MCP Request (e.g. sse)
|
|
BackendServer-->>FastMCPProxy: MCP Response (e.g. sse)
|
|
Note over ClientApp, FastMCPProxy: Proxy relays the response
|
|
FastMCPProxy-->>ClientApp: MCP Response (e.g. stdio)
|
|
```
|
|
### Use Cases
|
|
|
|
- **Transport Bridging**: Expose a server running on one transport (e.g., a remote SSE server) via a different transport (e.g., local Stdio for Claude Desktop).
|
|
- **Adding Functionality**: Insert a layer in front of an existing server to add caching, logging, authentication, or modify requests/responses (though direct modification requires subclassing `FastMCPProxy`).
|
|
- **Security Boundary**: Use the proxy as a controlled gateway to an internal server.
|
|
- **Simplifying Client Configuration**: Provide a single, stable endpoint (the proxy) even if the backend server's location or transport changes.
|
|
|
|
## Creating a Proxy
|
|
|
|
The easiest way to create a proxy is using the `FastMCP.as_proxy()` class method. This creates a standard FastMCP server that forwards requests to another MCP server.
|
|
|
|
```python
|
|
from fastmcp import FastMCP
|
|
|
|
# Provide the backend in any form accepted by Client
|
|
proxy_server = FastMCP.as_proxy(
|
|
"backend_server.py", # Could also be a FastMCP instance or a remote URL
|
|
name="MyProxyServer" # Optional settings for the proxy
|
|
)
|
|
|
|
# Or create the Client yourself for custom configuration
|
|
backend_client = Client("backend_server.py")
|
|
proxy_from_client = FastMCP.as_proxy(backend_client)
|
|
```
|
|
|
|
**How `as_proxy` Works:**
|
|
|
|
1. It connects to the backend server using the provided client.
|
|
2. It discovers all the tools, resources, resource templates, and prompts available on the backend server.
|
|
3. It creates corresponding "proxy" components that forward requests to the backend.
|
|
4. It returns a standard `FastMCP` server instance that can be used like any other.
|
|
|
|
<Note>
|
|
Currently, proxying focuses primarily on exposing the major MCP objects (tools, resources, templates, and prompts). Some advanced MCP features like notifications and sampling are not fully supported in proxies in the current version. Support for these additional features may be added in future releases.
|
|
</Note>
|
|
|
|
### Bridging Transports
|
|
|
|
A common use case is to bridge transports. For example, making a remote SSE server available locally via Stdio:
|
|
|
|
```python
|
|
from fastmcp import FastMCP
|
|
|
|
# Target a remote SSE server directly by URL
|
|
proxy = FastMCP.as_proxy("http://example.com/mcp/sse", name="SSE to Stdio Proxy")
|
|
|
|
# The proxy can now be used with any transport
|
|
# No special handling needed - it works like any FastMCP server
|
|
```
|
|
|
|
### In-Memory Proxies
|
|
|
|
You can also proxy an in-memory `FastMCP` instance, which is useful for adjusting the configuration or behavior of a server you don't completely control.
|
|
|
|
```python
|
|
from fastmcp import FastMCP
|
|
|
|
# Original server
|
|
original_server = FastMCP(name="Original")
|
|
|
|
@original_server.tool()
|
|
def tool_a() -> str:
|
|
return "A"
|
|
|
|
# Create a proxy of the original server directly
|
|
proxy = FastMCP.as_proxy(
|
|
original_server,
|
|
name="Proxy Server"
|
|
)
|
|
|
|
# proxy is now a regular FastMCP server that forwards
|
|
# requests to original_server
|
|
```
|
|
|
|
## `FastMCPProxy` Class
|
|
|
|
Internally, `FastMCP.as_proxy()` uses the `FastMCPProxy` class. You generally don't need to interact with this class directly, but it's available if needed.
|
|
|
|
Using the class directly might be necessary for advanced scenarios, like subclassing `FastMCPProxy` to add custom logic before or after forwarding requests. |