Integrating Multiple MCP Server to an Agent

Welcome to the next step in your MCP-Agent integration journey! In the previous lessons, you mastered connecting an OpenAI agent to a single MCP server and optimized that connection using tool caching. Now you're ready to tackle a more complex and realistic scenario: building an agent that can coordinate across multiple MCP servers simultaneously.

In this lesson, you'll build a shopping assistant that connects to two different MCP servers at once. The first server manages your shopping list (adding items, marking them as purchased), while the second server handles product ordering from a catalog. This setup mirrors real-world applications where different services handle different aspects of a workflow, and your agent needs to orchestrate between them intelligently.

Why does this matter? Most practical AI applications don't operate in isolation. Consider a travel booking agent that needs to check flight availability, reserve hotel rooms, and update your calendar. Or a project management assistant that creates tasks, assigns team members, and sends notifications. These scenarios require your agent to coordinate multiple specialized services, each with its own tools and capabilities.

When you connect multiple MCP servers to a single agent, you're giving your agent access to tools from different specialized services. Each server runs independently, but the agent treats all their tools as one unified toolkit.

You're already familiar with your shopping list server from previous lessons - it provides tools like get_items, add_item, and set_purchased for managing your shopping list. Now you're adding a second server: the order products server. This new server handles suppliers and ordering with tools like get_suppliers and place_order.

The two servers complement each other perfectly. Your shopping list server knows what items you need, while the ordering server can find suppliers and place orders. Together, they enable complex workflows like "order all unpurchased items from my shopping list" - the agent uses your shopping list server to identify what needs purchasing, then coordinates with the ordering server to complete the purchases.

The agent automatically discovers all tools from both servers during initialization and intelligently chooses which tools to use based on the task at hand. Clear tool naming helps the agent understand which server handles what - get_items clearly retrieves shopping list items, while get_suppliers obviously finds product suppliers.

Setting up multiple MCP servers follows the same pattern you learned in previous lessons, but now you'll create two separate server instances. Each server runs as its own process and maintains its own connection to your agent.

You can configure your servers using any combination of connection types - both as MCPServerStdio, both as MCPServerStreamableHttp, or mixing the two approaches based on your specific needs. Here's an example using stdio connections for both:

import { Agent, MCPServerStdio, run } from '@openai/agents';

// Configure the shopping list MCP server
const shoppingListServer = new MCPServerStdio({
  name: "Shopping List",
  command: "npx",
  args: ["tsx", "mcp-servers/list/server.ts"],
  cacheToolsList: true
});

// Configure the products MCP server
const orderProductsServer = new MCPServerStdio({
  name: "Order Products",
  command: "npx",
  args: ["tsx", "mcp-servers/products/server.ts"],
  cacheToolsList: true
});

The name field is particularly important here because it helps you identify which server is which in logs and debugging output. Each server points to its own implementation file that handles the specific MCP server logic for that domain.

You could equally well use HTTP connections for one or both servers, or mix connection types based on your deployment requirements. The key is that each server maintains its own independent connection to your agent, regardless of the connection type you choose.

Once you've defined your server configurations, you need to establish connections to both servers before creating your agent. You can connect to the servers either sequentially or in parallel, depending on your preference and error handling requirements.

try {
  // Connect to both MCP servers (sequential approach)
  await shoppingListServer.connect();
  await orderProductsServer.connect();

  // Alternative: Connect in parallel for faster startup
  // await Promise.all([
  //   shoppingListServer.connect(),
  //   orderProductsServer.connect()
  // ]);

  // Create the agent with both MCP servers
  const agent = new Agent({
    name: "Shopping & Order Assistant",
    instructions: (
      "You are an assistant that can manage shopping lists and handle product ordering from suppliers. " +
      "You can add items to shopping lists, mark them as purchased, " +
      "find suppliers, and place orders."
    ),
    mcpServers: [
      shoppingListServer,
      orderProductsServer
    ],
    model: "gpt-5.6-terra",
    modelSettings: { providerData: { reasoning: { effort: "none" } } },
  });
  
  // Requests to the agent...
  
} finally {
  // Close the connection to both MCP servers
  await shoppingListServer.close();
  await orderProductsServer.close();
}

Sequential connections give you clearer error messages if one specific server fails, while parallel connections reduce startup time. When creating the agent, you pass both servers in the mcpServers array - the agent will discover and catalog all tools from both servers during initialization.

Once your servers are connected, creating and running the agent follows the same pattern as single-server setups, but now the agent has access to tools from both servers and can coordinate between them automatically.

// Run the agent with a complex request spanning both servers
const result = await run(
  agent,
  "Order all the unpurchased items in the shopping list"
);

// Print the final output
console.log(result.finalOutput);

The agent automatically discovers all available tools from both servers during initialization and treats them as one unified toolkit. When you provide a complex request like ordering unpurchased items, the agent intelligently breaks it down into steps: first retrieving unpurchased items from the shopping list server, then finding appropriate suppliers from the ordering server, and finally placing orders for each item with the correct supplier.

The agent's decision-making relies on tool names and descriptions from both servers, so clear, descriptive naming becomes crucial for helping the agent route requests correctly and understand dependencies between operations across different servers.

When you run the multi-server agent with a complex request, you'll see how it coordinates tools across both servers to accomplish the task. Here's what the output might look like:

All unpurchased items from your shopping list have been ordered:

- Bread (1 unit) from General Goods Inc
- Apples (6 units) from Fresh Fruits Co
- Coffee (1 unit) from General Goods Inc

Would you like to do anything else, such as mark these items as purchased or see your order status?

Behind the scenes, the agent coordinated multiple tool calls across both servers: first using the shopping list server's get_items tool to retrieve unpurchased items, then calling the ordering server's get_suppliers tool to find appropriate suppliers for different product categories, and finally using place_order to complete each purchase. The agent automatically determined the sequence of operations needed and selected the appropriate tools from each server to fulfill the complete request.

This demonstrates the power of multi-server integration - the agent seamlessly orchestrates complex workflows that span different specialized services, presenting a unified experience to the user while managing the underlying coordination complexity.

You can also examine exactly which tools were called and in what order using the helper function we developed to trace the agent's coordination across both servers:

// Print the conversation history in a readable format
printToolHistory(result.history);

This might produce output like:

GET_ITEMS
Arguments: purchased: "false"
Result: {
  "success": true,
  "message": "Retrieved 3 item(s)",
  "data": [
    {
      "id": "2f6cd2c9-8257-402b-a8ea-85e20d45ea5e",
      "name": "Bread",
      "quantity": 1,
      "purchased": false
    },
    ...
  ]
}

GET_SUPPLIERS
Arguments: category: "general"
Result: {
  "success": true,
  "message": "Retrieved 1 supplier(s)",
  "data": [
    {
      "id": "d42a7fef-4970-49fa-a5b4-b2447a9a006c",
      "name": "General Goods Inc",
      "category": "general"
    }
  ]
}

...

PLACE_ORDER
Arguments: supplier_id: "d42a7fef-4970-49fa-a5b4-b2447a9a006c", product_name: "Bread", quantity: "1"
Result: {
  "success": true,
  "message": "Order placed successfully",
  "data": {
    "orderId": "c34511fc-500e-42fa-bb50-8a5349de0f4d"
  }
}

The tool history reveals how the agent systematically used the shopping list server to identify unpurchased items, then coordinated with the ordering server to find suppliers and place orders for each item. This visibility into the agent's decision-making process is invaluable for debugging and understanding how your multi-server coordination is working in practice.

You've now mastered connecting multiple MCP servers to a single agent, enabling sophisticated workflows that span different specialized services. The key concepts include configuring multiple server instances, establishing connections (sequentially or in parallel), passing multiple servers to the agent through the mcpServers array, and handling proper cleanup of all connections.

In the upcoming practice exercises, you'll extend this foundation by adding more servers, handling failure scenarios gracefully, and building more complex coordination workflows that demonstrate the full power of multi-server agent integration.