Connecting OpenAI Agents to MCP Servers

Welcome back! Now that you've built your MCP server and exposed your shopping list tools, it's time to make them available to an OpenAI agent. The OpenAI Agents SDK has built-in support for MCP tools, allowing you to seamlessly integrate any MCP server with your agents. In this lesson, you'll learn how the SDK uses MCP clients to connect to servers, and how to set up connections using both stdio and HTTP streaming transport.

By the end of this lesson, you'll be able to:

• Understand how the OpenAI Agents SDK integrates with MCP servers through clients
• Connect an OpenAI agent to your MCP server using both stdio and HTTP streaming transport
• Provide MCP servers to agents so they can discover and use your tools
• Run and test the integration, verifying that the agent can answer queries using your shopping list service

Let's walk through each step in detail.

The OpenAI Agents SDK includes built-in support for the Model Context Protocol (MCP). It achieves this by using MCP clients that connect to your MCP servers. These clients handle all the communication details, allowing your agent to:

• Discover available tools from connected MCP servers
• Read tool documentation and input schemas
• Execute tools in response to user queries
• Aggregate tools from multiple MCP servers

The SDK provides different client implementations depending on how your MCP server is running:

• MCPServerStdio for local processes communicating via standard input/output
• MCPServerStreamableHttp for servers accessible over HTTP

These clients abstract away the complexity of the MCP protocol, making it simple to integrate any MCP server with your agents.

When your MCP server is a local TypeScript file or executable, you can use the MCPServerStdio class. This approach spawns your server as a subprocess and communicates through standard input/output streams.

Here's how to connect using stdio:

import { MCPServerStdio } from '@openai/agents';

// Define the MCP server configuration for stdio transport
const mcpServer = new MCPServerStdio({
  name: "Shopping List Server",
  command: "npx",
  args: ["tsx", "server.ts"]
});

try {
  // Connect to the MCP server
  await mcpServer.connect();
  
  // Your agent code goes here...
} finally {
  // Always close the connection to clean up resources
  await mcpServer.close();
}

Key parameters:

• name: A friendly name for debugging and logging
• command: The command to execute (in this case, npx)
• args: Arguments to pass to the command (tsx server.ts runs your TypeScript server)

This approach is perfect for development and testing, as it automatically manages the server lifecycle alongside your agent.

When your MCP server is running as a standalone HTTP service — whether locally or remotely — you'll use the MCPServerStreamableHttp class. This allows the agent to communicate with your server over HTTP, making it suitable for distributed or production environments.

Here's how to connect using HTTP streaming:

import { MCPServerStreamableHttp } from '@openai/agents';

// Define the MCP server configuration for Streamable HTTP transport
const mcpServer = new MCPServerStreamableHttp({
  name: "Shopping List Server",
  url: "http://localhost:3000/mcp"
});

try {
  // Connect to the MCP server
  await mcpServer.connect();
  
  // Your agent code goes here...
} finally {
  // Always close the connection to clean up resources
  await mcpServer.close();
}

Key parameters:

• name: A friendly name for debugging and logging
• url: The HTTP endpoint where your MCP server is listening

This approach gives you more flexibility in deployment, as your MCP server can run anywhere accessible via HTTP.

Once you have an MCP client connected to your server, you can provide it to your agent through the mcpServers property. The agent will automatically discover all tools exposed by your connected servers.

Here's a complete example using HTTP streaming:

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

// MCP server configuration...

try {
  // Connect to the MCP server
  await mcpServer.connect();

  // Create the agent with the MCP server connection
  const agent = new Agent({
    name: "Shopping Assistant",
    instructions: (
      "You are an assistant that uses shopping list tools to help manage a shopping list."
    ),
    mcpServers: [mcpServer],
    model: "gpt-5.6-terra",
    modelSettings: { providerData: { reasoning: { effort: "none" } } },
  });

  // Run the agent with a query
  const result = await run(
    agent,
    "Add ingredients for chocolate chip cookies to my shopping list"
  );

  // Print the final output
  console.log(result.finalOutput);
} finally {
  // Always close the connection to clean up resources
  await mcpServer.close();
}

When you run this code, you'll see an output like:

All the necessary ingredients for chocolate chip cookies have been added to your shopping list.

Here's your full shopping list with purchased status:

1. Milk (2) - purchased
2. Bread (1) - not purchased
3. Eggs (12) - purchased
4. Apples (6) - not purchased
5. Coffee (1) - not purchased
6. All-purpose flour (1) - not purchased
7. Granulated sugar (1) - not purchased
8. Brown sugar (1) - not purchased
9. Eggs (2) - not purchased
10. Vanilla extract (1) - not purchased
11. Unsalted butter (1) - not purchased
12. Salt (1) - not purchased
13. Chocolate chips (1) - not purchased
14. Baking soda (1) - not purchased

If you want to mark items as purchased or need any more items added, just let me know!

Notice how the agent understood your request and automatically made multiple tool calls — it added each ingredient individually using add_item, then called get_items to show the complete list. The agent knew which ingredients were needed for chocolate chip cookies without being explicitly told, and formatted everything into a helpful response showing quantities and purchase status. This seamless interaction demonstrates the power of MCP integration: your agent discovered and used your tools automatically based on their schemas and documentation.

When you provide MCP servers to the agent, it automatically:

1. Connects to each server and requests the list of available tools
2. Reads the documentation and input schemas for each tool
3. Aggregates all tools into a single tool set
4. Uses these tools to respond to user queries

For example, when asked to "Add ingredients for chocolate chip cookies to my shopping list", the agent:

• Recognizes it needs to use the add_item tool multiple times
• Calls the tool with appropriate parameters for each ingredient
• Uses get_items to retrieve the full list
• Formats a helpful response showing all items

This automatic discovery and tool usage is what makes MCP integration so powerful — your agent can flexibly use any tool you expose without additional programming.

To understand how your agent uses MCP tools, we'll use a helper function that explores the execution history. The printToolHistory() function parses through the agent's history and displays each tool call in a readable format:

// Helper function to format arguments nicely
function formatArguments(args: any): string {
  const formatted = Object.entries(args)
    .map(([key, value]) => `${key}: "${value}"`)
    .join(", ");
  return formatted || "none";
}

// Function to format and print tool usage history
export function printToolHistory(history: any[]) {
  for (const item of history) {
    // Process tool calls
    if (item.type === "function_call" && item.status === "completed") {
      const args = JSON.parse(item.arguments || "{}");
      
      console.log(`\n${item.name.toUpperCase()}`);
      console.log(`Arguments: ${formatArguments(args)}`);
      
      // Find the corresponding result
      const result = history.find(h => 
        h.type === "function_call_result" && 
        h.callId === item.callId
      );
      
      if (result?.output?.text) {
        const resultData = JSON.parse(result.output.text);
        const resultText = resultData.text || resultData;
        console.log(`Result: ${resultText}`);
      }
    }
  }
}

This helper function:

• Iterates through the agent's execution history
• Identifies completed function calls (tool uses)
• Formats the arguments passed to each tool
• Matches each call with its corresponding result
• Displays everything in a clean, readable format

Using this function after running your agent:

import { printToolHistory } from './utils.js';

// After running the agent
printToolHistory(result.history);

Produces output like:

Tool Usage History:

ADD_ITEM
Arguments: name: "all-purpose flour", quantity: "1"
Result: {
  "success": true,
  "message": "Item added successfully",
  "data": {
    "id": "282fa3e1-a2a5-4f26-8e85-6323ec6346e9",
    "name": "all-purpose flour",
    "quantity": 1,
    "purchased": false
  }
}

ADD_ITEM
Arguments: name: "granulated sugar", quantity: "1"
Result: {
  "success": true,
  "message": "Item added successfully",
  "data": {
    "id": "eede554d-a7bd-4e33-9bba-edc162112c8f",
    "name": "granulated sugar",
    "quantity": 1,
    "purchased": false
  }
}

... (more ADD_ITEM calls for other ingredients) ...

GET_ITEMS
Arguments: none
Result: {
  "success": true,
  "message": "Retrieved 14 item(s)",
  "data": [
    {
      "id": "25924f29-ea62-445d-9b4c-f07b9d6e7415",
      "name": "Milk",
      "quantity": 2,
      "purchased": true
    },
    ... (full list of items) ...
  ]
}

Notice how the agent understood your request and automatically made multiple tool calls — it added each ingredient individually using add_item, then called get_items to show the complete list. The agent knew which ingredients were needed for chocolate chip cookies without being explicitly told, and formatted everything into a helpful response showing quantities and purchase status. This seamless interaction demonstrates the power of MCP integration: your agent discovered and used your tools automatically based on their schemas and documentation.

In this lesson, you learned how the OpenAI Agents SDK supports MCP tools through built-in clients. You saw how to connect to MCP servers using both stdio (for local TypeScript files) and HTTP streaming (for standalone services). You learned how to provide these connections to your agent, enabling automatic tool discovery and usage.

You explored real examples of how an agent uses your tools — making multiple add_item calls to add ingredients, then using get_items to retrieve and display the full shopping list. You also learned how to use the printToolHistory() helper function to explore the agent's execution history, giving you deep insight into how your tools are being used.

You're now ready to practice these skills by building and testing your own agent-server integrations. This is a major milestone — your tools are now available to intelligent agents that can use them in flexible, conversational ways. In the next exercises, you'll get hands-on experience with these integrations and deepen your understanding of TypeScript-based MCP development.