Server Proxying & Composition

The mcp-use TypeScript SDK allows you to easily proxy and compose multiple MCP servers into a single unified "Aggregator" server.

This is extremely useful when you have multiple microservices or specialized MCP servers (like a database server, a weather server, and an internal API server) and you want to expose all of their tools, resources, and prompts through a single unified endpoint.

High-Level API (Config Object)

Pass a configuration object directly to server.proxy(). The keys act as the namespaces for the child servers to prevent naming collisions.

import { MCPServer } from "mcp-use/server";
import path from "node:path";

const server = new MCPServer({ name: "UnifiedServer", version: "1.0.0" });

// The SDK handles all connections, sessions, and synchronization automatically
await server.proxy({
  // Proxy a local TypeScript server (using the 'tsx' runner)
  database: {
    command: "tsx",
    args: [path.resolve(__dirname, "./db-server.ts")]
  },
  
  // Proxy a local Python FastMCP server
  weather: {
    command: "uv",
    args: ["run", "weather_server.py"],
    env: { ...process.env, FASTMCP_LOG_LEVEL: "ERROR" }
  },
  
  // Proxy a remote server over HTTP
  manufact: {
    url: "https://manufact.com/docs/mcp"
  }
});

// Start the unified server
await server.listen(3000);

In the example above, the database tools will be prefixed with database_ (e.g. database_query), the weather tools will be prefixed with weather_ (e.g. weather_get_forecast), and so on. Resource URIs will be prefixed like database://app://config.

Low-Level API (Explicit Session)

For advanced use cases (dynamic auth headers, manual session lifecycles, or custom connectors), you can inject an explicit MCPSession directly into the proxy method using the mcp-use/client SDK.

import { MCPServer } from "mcp-use/server";
import { MCPClient } from "mcp-use/client";

const server = new MCPServer({ name: "UnifiedServer", version: "1.0.0" });

// Create a custom client orchestration
const customClient = new MCPClient({
  mcpServers: {
    secure_db: {
      url: "https://secure-db.example.com/mcp"
    }
  }
});

// Manage the session manually
const dbSession = await customClient.createSession("secure_db");

// Proxy the active session, manually specifying the namespace
await server.proxy(dbSession, { namespace: "secure_db" });

await server.listen(3000);

Advanced Features Supported

The mcp-use proxying system goes far beyond simple tool forwarding:

1. Schema Translation: Automatically translates raw JSON Schemas from child servers into runtime Zod schemas.
2. LLM Sampling & Elicitation: Automatically intercepts out-of-band JSONRPC requests (sampling/elicitation) from child servers, resolves the HTTP context of the original user who triggered the tool, and routes the request securely back to that user's client.
3. Progress Tracking: If a child tool emits notifications/progress/report, the Aggregator catches and pipes those directly through the unified ToolContext back to the parent client.
4. State Syncing: The Aggregator listens to list_changed events emitted by the child server and instantly forwards them to all connected clients.