1# Server Proxying & Composition
2 
3The `mcp-use` TypeScript SDK allows you to easily proxy and compose multiple MCP servers into a single unified "Aggregator" server.
4 
5This 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.
6 
7## High-Level API (Config Object)
8 
9Pass a configuration object directly to `server.proxy()`. The keys act as the **namespaces** for the child servers to prevent naming collisions.
10 
11```typescript
12import { MCPServer } from "mcp-use/server";
13import path from "node:path";
14 
15const server = new MCPServer({ name: "UnifiedServer", version: "1.0.0" });
16 
17// The SDK handles all connections, sessions, and synchronization automatically
18await server.proxy({
19  // Proxy a local TypeScript server (using the 'tsx' runner)
20  database: {
21    command: "tsx",
22    args: [path.resolve(__dirname, "./db-server.ts")]
23  },
24  
25  // Proxy a local Python FastMCP server
26  weather: {
27    command: "uv",
28    args: ["run", "weather_server.py"],
29    env: { ...process.env, FASTMCP_LOG_LEVEL: "ERROR" }
30  },
31  
32  // Proxy a remote server over HTTP
33  manufact: {
34    url: "https://manufact.com/docs/mcp"
35  }
36});
37 
38// Start the unified server
39await server.listen(3000);
40```
41 
42In 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`.
43 
44## Low-Level API (Explicit Session)
45 
46For 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.
47 
48```typescript
49import { MCPServer } from "mcp-use/server";
50import { MCPClient } from "mcp-use/client";
51 
52const server = new MCPServer({ name: "UnifiedServer", version: "1.0.0" });
53 
54// Create a custom client orchestration
55const customClient = new MCPClient({
56  mcpServers: {
57    secure_db: {
58      url: "https://secure-db.example.com/mcp"
59    }
60  }
61});
62 
63// Manage the session manually
64const dbSession = await customClient.createSession("secure_db");
65 
66// Proxy the active session, manually specifying the namespace
67await server.proxy(dbSession, { namespace: "secure_db" });
68 
69await server.listen(3000);
70```
71 
72## Advanced Features Supported
73 
74The `mcp-use` proxying system goes far beyond simple tool forwarding:
75 
761. **Schema Translation**: Automatically translates raw JSON Schemas from child servers into runtime Zod schemas.
772. **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. 
783. **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.
794. **State Syncing**: The Aggregator listens to `list_changed` events emitted by the child server and instantly forwards them to all connected clients.
80