How to combine multiple MCP servers into one

{
  "name": "mcp-gateway-demo",
  "private": true,
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/client": "2.0.0",
    "@modelcontextprotocol/server": "2.0.0",
    "zod": "4.4.3"
  }
}

npm install

// upstream-weather.ts: a tiny MCP server, standing in for a real one.
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const CITIES = ["Lisbon", "Reykjavik", "Nairobi"];

function makeServer() {
  const server = new McpServer({ name: "weather", version: "1.0.0" });

  server.registerTool(
    "search",
    {
      description: "Search the city list. Returns matching city names.",
      inputSchema: z.object({ query: z.string() }),
    },
    async ({ query }) => {
      const hits = CITIES.filter((c) =>
        c.toLowerCase().includes(query.toLowerCase()),
      );
      return { content: [{ type: "text", text: hits.join(", ") || "no match" }] };
    },
  );

  server.registerTool(
    "forecast",
    {
      description: "Get tomorrow's forecast for a city.",
      inputSchema: z.object({ city: z.string() }),
    },
    async ({ city }) => {
      if (!CITIES.includes(city)) throw new Error(`Unknown city: ${city}`);
      return { content: [{ type: "text", text: `${city}: 18C, light rain` }] };
    },
  );

  return server;
}

serveStdio(() => makeServer());

// upstream-notes.ts: a second MCP server. Note that it also has a "search" tool.
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const NOTES = [
  { id: "n1", title: "Standup", body: "Ship the gateway." },
  { id: "n2", title: "Groceries", body: "Coffee, oats." },
];

function makeServer() {
  const server = new McpServer({ name: "notes", version: "1.0.0" });

  server.registerTool(
    "search",
    {
      description: "Search notes by title. Returns matching note ids.",
      inputSchema: z.object({ query: z.string() }),
    },
    async ({ query }) => {
      const hits = NOTES.filter((n) =>
        n.title.toLowerCase().includes(query.toLowerCase()),
      );
      const text = hits.map((n) => `${n.id}: ${n.title}`).join("\n");
      return { content: [{ type: "text", text: text || "no match" }] };
    },
  );

  server.registerTool(
    "read",
    {
      description: "Read one note by id.",
      inputSchema: z.object({ id: z.string() }),
    },
    async ({ id }) => {
      const note = NOTES.find((n) => n.id === id);
      if (!note) throw new Error(`No note with id ${id}`);
      return { content: [{ type: "text", text: note.body }] };
    },
  );

  return server;
}

serveStdio(() => makeServer());

{
  "servers": [
    { "name": "weather", "command": "node", "args": ["upstream-weather.ts"] },
    { "name": "notes", "command": "node", "args": ["upstream-notes.ts"] },
    { "name": "broken", "command": "node", "args": ["does-not-exist.ts"] }
  ]
}

// gateway.ts: one MCP server that fronts several others.
import { readFileSync } from "node:fs";
import { McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

type Upstream = { name: string; command: string; args: string[] };

type Route = {
  client: Client;
  toolName: string;
  description?: string;
  inputSchema: any;
};

const config: { servers: Upstream[] } = JSON.parse(
  readFileSync("servers.json", "utf8"),
);

// One entry per upstream tool, keyed by the name the gateway exposes.
const routes = new Map<string, Route>();

async function connectUpstream(entry: Upstream): Promise<number> {
  const client = new Client({ name: "gateway", version: "1.0.0" });
  const transport = new StdioClientTransport({
    command: entry.command,
    args: entry.args,
    stderr: "ignore",
  });
  await client.connect(transport);

  const { tools } = await client.listTools();
  for (const tool of tools) {
    routes.set(`${entry.name}.${tool.name}`, {
      client,
      toolName: tool.name,
      description: tool.description,
      inputSchema: tool.inputSchema,
    });
  }
  return tools.length;
}

// Connect to every upstream before serving. One dead server must not take the
// gateway down with it, so a failure is logged and skipped.
for (const entry of config.servers) {
  try {
    const count = await connectUpstream(entry);
    console.error(`[gateway] ${entry.name}: ${count} tools`);
  } catch (error) {
    console.error(`[gateway] ${entry.name} unavailable: ${(error as Error).message}`);
  }
}

function makeServer(): McpServer {
  const server = new McpServer({ name: "gateway", version: "1.0.0" });

  for (const [publicName, route] of routes) {
    server.registerTool(
      publicName,
      {
        description: route.description,
        // The upstream already published a JSON Schema. Pass it straight
        // through instead of rebuilding it by hand.
        inputSchema: fromJsonSchema(route.inputSchema),
      },
      async (args) => {
        return await route.client.callTool({
          name: route.toolName,
          arguments: args as Record<string, unknown>,
        });
      },
    );
  }

  return server;
}

serveStdio(() => makeServer());

// test.ts: connect to the gateway and exercise tools from both upstreams.
import assert from "node:assert/strict";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

const client = new Client({ name: "test", version: "1.0.0" });
await client.connect(
  new StdioClientTransport({ command: "node", args: ["gateway.ts"] }),
);

const { tools } = await client.listTools();
const names = tools.map((t) => t.name).sort();
console.log("TOOLS:", names.join(", "));

// Both upstreams export a tool called "search". The prefix keeps them apart.
assert.deepEqual(names, [
  "notes.read",
  "notes.search",
  "weather.forecast",
  "weather.search",
]);

// The unreachable upstream in servers.json did not stop the gateway.
assert.ok(!names.some((n) => n.startsWith("broken.")));

const forecast = await client.callTool({
  name: "weather.forecast",
  arguments: { city: "Lisbon" },
});
console.log("weather.forecast ->", forecast.content[0].text);
assert.match(forecast.content[0].text, /Lisbon/);

const note = await client.callTool({
  name: "notes.read",
  arguments: { id: "n1" },
});
console.log("notes.read ->", note.content[0].text);
assert.equal(note.content[0].text, "Ship the gateway.");

// Each "search" reaches its own upstream, not the other one.
const cities = await client.callTool({
  name: "weather.search",
  arguments: { query: "re" },
});
console.log("weather.search ->", cities.content[0].text);
assert.equal(cities.content[0].text, "Reykjavik");

const notes = await client.callTool({
  name: "notes.search",
  arguments: { query: "stand" },
});
console.log("notes.search ->", notes.content[0].text);
assert.equal(notes.content[0].text, "n1: Standup");

// An upstream error comes back as a tool error, not a dead gateway.
const missing = await client.callTool({
  name: "notes.read",
  arguments: { id: "nope" },
});
assert.equal(missing.isError, true);
console.log("notes.read (bad id) -> isError:", missing.isError);

// The gateway is still usable after that error.
const again = await client.callTool({
  name: "notes.read",
  arguments: { id: "n2" },
});
assert.equal(again.content[0].text, "Coffee, oats.");

await client.close();
console.log("ALL CHECKS PASSED");

[gateway] weather: 2 tools
[gateway] notes: 2 tools
[gateway] broken unavailable: Connection closed
TOOLS: notes.read, notes.search, weather.forecast, weather.search
weather.forecast -> Lisbon: 18C, light rain
notes.read -> Ship the gateway.
weather.search -> Reykjavik
notes.search -> n1: Standup
notes.read (bad id) -> isError: true
ALL CHECKS PASSED

// Two upstreams, both with a tool called "search".
server.registerTool("search", { description: "A", inputSchema: z.object({ q: z.string() }) }, handlerA);
server.registerTool("search", { description: "B", inputSchema: z.object({ q: z.string() }) }, handlerB);

// Error: Tool search is already registered