Struct McpProxy 

pub struct McpProxy { /* private fields */ }

An MCP proxy that aggregates multiple backend servers.

Implements Service<RouterRequest> so it can be used with any tower-mcp transport (HTTP, WebSocket, stdio) and composed with tower middleware.

Each backend’s capabilities are namespaced to avoid collisions, and individual backends can have their own Tower middleware stack applied via McpProxyBuilder::backend_layer().

Backends can be added dynamically at runtime via add_backend(). All clones of the proxy share the same backend list, so additions are immediately visible to all request handlers.

Implementations

impl McpProxy

pub fn builder( name: impl Into<String>, version: impl Into<String>, ) -> McpProxyBuilder

Create a builder for configuring the proxy.

pub async fn add_backend( &self, namespace: impl Into<String>, transport: impl ClientTransport, ) -> Result<(), AddBackendError>

Add a backend dynamically from a ClientTransport.

The transport is connected, the MCP initialize handshake runs, and capabilities are discovered. The new backend is immediately available to all clones of this proxy.

Errors

Returns an error if:

• The namespace is already in use
• The namespace creates an ambiguous prefix with an existing backend
• The transport fails to connect
• The MCP initialize handshake fails

Example

proxy.add_backend("new-db", StdioClientTransport::spawn("db-server", &[]).await?).await?;
// New backend is immediately available for requests

pub async fn add_backend_with_layer<L>( &self, namespace: impl Into<String>, transport: impl ClientTransport, layer: L, ) -> Result<(), AddBackendError>

where L: Layer<BackendService> + Send + 'static, L::Service: Service<RouterRequest, Response = RouterResponse> + Clone + Send + 'static, <L::Service as Service<RouterRequest>>::Error: Display + Send, <L::Service as Service<RouterRequest>>::Future: Send,

Add a backend dynamically with a custom middleware-wrapped service.

Like add_backend(), but applies a Tower layer to the backend’s dispatch service before adding it.

Example

use std::time::Duration;
use tower::timeout::TimeoutLayer;

proxy.add_backend_with_layer(
    "slow-api",
    transport,
    TimeoutLayer::new(Duration::from_secs(60)),
).await?;

pub async fn remove_backend(&self, namespace: &str) -> bool

Remove a backend by namespace name.

The backend’s tools, resources, and prompts are immediately removed from aggregated lists. Downstream clients are notified via list-changed notifications.

Returns true if the backend was found and removed, false if no backend with that namespace exists.

Example

if proxy.remove_backend("old-db").await {
    println!("Backend removed");
}

pub async fn replace_backend( &self, namespace: impl Into<String>, transport: impl ClientTransport, ) -> Result<(), AddBackendError>

Replace a backend by removing the old one and adding a new one with the same namespace.

This is a convenience for remove_backend() + add_backend(). If the add fails, the old backend is already gone (no rollback).

Example

proxy.replace_backend("db", new_transport).await?;

pub fn backend_namespaces(&self) -> Vec<String>

Return the namespaces of all currently registered backends.

Example

let namespaces = proxy.backend_namespaces();
println!("Backends: {:?}", namespaces);

pub fn backend_count(&self) -> usize

Return the number of currently registered backends.

pub async fn health_check(&self) -> Vec<BackendHealth>

Check the health of all backends by pinging them concurrently.

Returns a map of namespace to health status. Backends that respond to ping within a reasonable time are considered healthy.

Trait Implementations

impl Clone for McpProxy

fn clone(&self) -> McpProxy

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Service<RouterRequest> for McpProxy

type Response = RouterResponse

Responses given by the service.

type Error = Infallible

Errors produced by the service.

type Future = Pin<Box<dyn Future<Output = Result<RouterResponse, Infallible>> + Send>>

The future response value.

fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, req: RouterRequest) -> Self::Future

Process the request and return the response asynchronously.