|
1 | | -# Multi-Server MCP Client Example |
| 1 | +# Multi-Server Routing Example |
2 | 2 |
|
3 | | -A CLI chatbot that connects to multiple MCP servers simultaneously, aggregates their tools, and routes tool calls to the correct server. This is the TypeScript equivalent of the [Python SDK's simple-chatbot example](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples/clients/simple-chatbot). |
| 3 | +Minimal example showing how to connect to multiple MCP servers and route tool calls to the correct one. |
4 | 4 |
|
5 | | -## Prerequisites |
| 5 | +Spawns two in-repo servers (`server-quickstart` and `mcpServerOutputSchema`), discovers their tools, builds a prefixed routing table, and calls one tool on each server to demonstrate the routing. |
6 | 6 |
|
7 | | -- Node.js 20+ |
8 | | -- An [Anthropic API key](https://console.anthropic.com/) |
| 7 | +No API key required. No external config file needed. |
9 | 8 |
|
10 | 9 | ## Quick Start |
11 | 10 |
|
12 | 11 | ```bash |
13 | 12 | # Install dependencies (from repo root) |
14 | 13 | pnpm install |
15 | 14 |
|
16 | | -# Set your API key |
17 | | -export ANTHROPIC_API_KEY=your-api-key-here |
18 | | - |
19 | | -# Run with the default servers.json config |
20 | | -cd examples/client-multi-server |
21 | | -npx tsx src/index.ts |
22 | | -``` |
23 | | - |
24 | | -## Configuration |
25 | | - |
26 | | -Servers are configured via a JSON file (default: `servers.json` in the working directory). Pass a custom path as the first argument: |
27 | | - |
28 | | -```bash |
29 | | -npx tsx src/index.ts /path/to/my-servers.json |
30 | | -``` |
31 | | - |
32 | | -The config file uses the same format as Claude Desktop and other MCP clients: |
33 | | - |
34 | | -```json |
35 | | -{ |
36 | | - "mcpServers": { |
37 | | - "everything": { |
38 | | - "command": "npx", |
39 | | - "args": ["-y", "@modelcontextprotocol/server-everything"] |
40 | | - }, |
41 | | - "memory": { |
42 | | - "command": "npx", |
43 | | - "args": ["-y", "@modelcontextprotocol/server-memory"] |
44 | | - } |
45 | | - } |
46 | | -} |
| 15 | +# Run the example |
| 16 | +npx tsx examples/client-multi-server/src/index.ts |
47 | 17 | ``` |
48 | 18 |
|
49 | | -Each entry under `mcpServers` defines a server to connect to via stdio: |
50 | | - |
51 | | -- `command`: the executable to run |
52 | | -- `args`: command-line arguments (optional) |
53 | | -- `env`: additional environment variables (optional, merged with the current environment) |
54 | | - |
55 | 19 | ## How It Works |
56 | 20 |
|
57 | | -1. Reads the server config and connects to each MCP server in sequence |
58 | | -2. Discovers tools from every connected server and builds a unified tool list |
59 | | -3. Maintains a mapping from each tool name to its originating server |
60 | | -4. Sends the full tool list to Claude with each request |
61 | | -5. When Claude calls a tool, routes the call to the correct server |
62 | | -6. Supports multi-step tool use (agentic loop) where Claude can chain multiple tool calls |
63 | | - |
64 | | -## Usage |
65 | | - |
66 | | -``` |
67 | | -$ npx tsx src/index.ts |
68 | | -Connecting to server: everything... |
69 | | - Connected to everything with tools: echo, add, ... |
70 | | -
|
71 | | -Total tools available: 12 |
| 21 | +1. Spawns each server as a child process via `StdioClientTransport` |
| 22 | +2. Connects a `Client` to each and calls `listTools()` to discover available tools |
| 23 | +3. Builds a routing map that prefixes each tool name with its server name (e.g. `weather-nws__get-alerts`) to avoid collisions |
| 24 | +4. Calls one tool on each server to prove routing works |
| 25 | +5. Cleans up all connections |
72 | 26 |
|
73 | | -Multi-Server MCP Client Started! |
74 | | -Type your queries or "quit" to exit. |
| 27 | +## Adapting This Pattern |
75 | 28 |
|
76 | | -Query: What tools do you have access to? |
| 29 | +To route tool calls in your own multi-server setup: |
77 | 30 |
|
78 | | -I have access to 12 tools from the "everything" server... |
79 | | -
|
80 | | -Query: quit |
81 | | -Disconnecting from everything... |
82 | | -``` |
| 31 | +- Prefix tool names with the server name when presenting them to an LLM |
| 32 | +- When the LLM calls a prefixed tool, strip the prefix and forward to the correct server |
| 33 | +- Check for collisions if multiple servers expose tools with the same name |
0 commit comments