MCP Integration Guide: OpenAI Agents SDK — Connect MCP Tools to OpenAI Agents

OpenAI's Agents SDK (formerly Swarm, now the production-ready framework for building multi-agent AI systems) has built-in support for tool use — but its native tools are defined in OpenAI's function-calling format. Integrating MCP servers with the OpenAI Agents SDK lets you reuse your existing MCP tool ecosystem inside OpenAI-powered agents without rewriting tool definitions.

This guide covers the full integration: bridging MCP tool schemas to OpenAI function format, calling MCP tools from agent workflows, and building multi-agent pipelines that combine OpenAI orchestration with MCP's rich tool ecosystem.

Why Connect MCP to the OpenAI Agents SDK

The MCP ecosystem has hundreds of production-ready servers covering databases, APIs, file systems, and SaaS integrations. The OpenAI Agents SDK provides the orchestration layer — handoffs between agents, guardrails, tracing, and multi-agent coordination. Combining them gives you:

• Reuse existing MCP servers — Any MCP server becomes available as an OpenAI agent tool without rewriting the integration
• Multi-agent + multi-tool — Specialized agents can each have access to different MCP server subsets, keeping context focused
• Vendor flexibility — Your tool layer (MCP) stays independent of your model/orchestration layer (OpenAI Agents SDK)
• Rich tool catalog — Filesystem, GitHub, databases, Slack, Notion — all immediately available to your OpenAI agents

How the Bridge Works

MCP and OpenAI function calling use similar but incompatible schemas. An MCP tool looks like:

// MCP tool definition
{
  name: "search_database",
  description: "Search the customer database",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" },
      limit: { type: "number" }
    },
    required: ["query"]
  }
}

An OpenAI function tool looks like:

// OpenAI function definition
{
  type: "function",
  function: {
    name: "search_database",
    description: "Search the customer database",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string" },
        limit: { type: "number" }
      },
      required: ["query"]
    }
  }
}

The schemas are nearly identical — the main difference is nesting. Converting between them is straightforward.

Step 1: Install Dependencies

npm install openai @openai/agents @modelcontextprotocol/sdk

Step 2: Build the MCP-to-OpenAI Bridge

// mcp-bridge.ts
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
import { tool } from '@openai/agents'

export interface MCPServerConfig {
  name: string
  command: string
  args?: string[]
  env?: Record
}

export async function mcpToAgentTools(config: MCPServerConfig) {
  // Connect to the MCP server
  const client = new Client(
    { name: 'openai-agents-bridge', version: '1.0.0' },
    { capabilities: {} }
  )

  const transport = new StdioClientTransport({
    command: config.command,
    args: config.args ?? [],
    env: { ...process.env, ...config.env }
  })

  await client.connect(transport)

  // Fetch available tools from the MCP server
  const { tools: mcpTools } = await client.listTools()

  // Convert each MCP tool to an OpenAI Agents SDK tool
  const agentTools = mcpTools.map((mcpTool) =>
    tool({
      name: mcpTool.name,
      description: mcpTool.description ?? '',
      parameters: mcpTool.inputSchema as any,
      execute: async (args) => {
        const result = await client.callTool({
          name: mcpTool.name,
          arguments: args
        })
        // Extract text content from MCP result
        const textContent = result.content
          .filter((c: any) => c.type === 'text')
          .map((c: any) => c.text)
          .join('
')
        return textContent
      }
    })
  )

  return { tools: agentTools, client }
}

Step 3: Build an Agent with MCP Tools

// agent.ts
import { Agent, run } from '@openai/agents'
import { mcpToAgentTools } from './mcp-bridge.js'

async function main() {
  // Load tools from multiple MCP servers
  const { tools: filesystemTools } = await mcpToAgentTools({
    name: 'filesystem',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/workspace']
  })

  const { tools: githubTools } = await mcpToAgentTools({
    name: 'github',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-github'],
    env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN! }
  })

  const { tools: searchTools } = await mcpToAgentTools({
    name: 'brave-search',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-brave-search'],
    env: { BRAVE_API_KEY: process.env.BRAVE_API_KEY! }
  })

  // Create a research agent with all three tool sets
  const researchAgent = new Agent({
    name: 'Research Assistant',
    instructions: `You are a research assistant with access to the filesystem,
    GitHub repositories, and web search. Use these tools to help users
    find information, analyze code, and research topics.`,
    tools: [...filesystemTools, ...githubTools, ...searchTools],
  })

  // Run the agent
  const result = await run(researchAgent, 'Search for recent MCP server implementations on GitHub and summarize what you find')
  console.log(result.finalOutput)
}

main().catch(console.error)

Step 4: Multi-Agent Architecture with Specialized MCP Tools

One of the Agents SDK's strengths is agent handoffs — the ability for one agent to delegate to a specialized agent. Combine this with MCP to create focused agents with tool subsets:

import { Agent, run } from '@openai/agents'
import { mcpToAgentTools } from './mcp-bridge.js'

async function buildMultiAgentSystem() {
  const { tools: dbTools } = await mcpToAgentTools({
    name: 'postgres',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-postgres', process.env.DATABASE_URL!]
  })

  const { tools: codeTools } = await mcpToAgentTools({
    name: 'filesystem',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', './src']
  })

  const { tools: commTools } = await mcpToAgentTools({
    name: 'slack',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-slack'],
    env: { SLACK_BOT_TOKEN: process.env.SLACK_BOT_TOKEN! }
  })

  // Specialized sub-agents
  const dataAgent = new Agent({
    name: 'Data Analyst',
    instructions: 'You analyze database data and generate insights.',
    tools: dbTools,
  })

  const codeAgent = new Agent({
    name: 'Code Reviewer',
    instructions: 'You review code files and identify issues.',
    tools: codeTools,
  })

  const commsAgent = new Agent({
    name: 'Communications Agent',
    instructions: 'You send notifications and updates via Slack.',
    tools: commTools,
  })

  // Orchestrator agent that delegates to specialists
  const orchestrator = new Agent({
    name: 'Orchestrator',
    instructions: `You coordinate between specialized agents.
    Delegate data analysis to the Data Analyst,
    code review to the Code Reviewer,
    and communications to the Communications Agent.`,
    tools: [
      dataAgent.asTool({ description: 'Analyze database data' }),
      codeAgent.asTool({ description: 'Review source code files' }),
      commsAgent.asTool({ description: 'Send Slack messages and notifications' }),
    ],
  })

  return orchestrator
}

Step 5: Handle MCP Server Lifecycle

MCP servers are separate processes. Manage their lifecycle properly in long-running agent deployments:

// Graceful shutdown of MCP clients
const clients: Client[] = []

process.on('SIGTERM', async () => {
  console.log('Shutting down MCP connections...')
  await Promise.all(clients.map(c => c.close()))
  process.exit(0)
})

// Keep MCP servers alive across multiple agent runs
// (reconnect logic for production deployments)
async function withRetry(fn: () => Promise, retries = 3): Promise {
  try {
    return await fn()
  } catch (err) {
    if (retries > 0) {
      await new Promise(resolve => setTimeout(resolve, 1000))
      return withRetry(fn, retries - 1)
    }
    throw err
  }
}

Using HTTP-Based MCP Servers

For MCP servers deployed on Cloud Run, Railway, or other platforms with SSE transport, use the HTTP client instead of stdio:

import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'

async function connectHTTPMCPServer(serverUrl: string, apiKey?: string) {
  const client = new Client(
    { name: 'openai-agents-bridge', version: '1.0.0' },
    { capabilities: {} }
  )

  const transport = new SSEClientTransport(
    new URL(`${serverUrl}/sse`),
    apiKey ? {
      requestInit: {
        headers: { Authorization: `Bearer ${apiKey}` }
      }
    } : undefined
  )

  await client.connect(transport)
  return client
}

Tracing and Observability

The OpenAI Agents SDK has built-in tracing support. MCP tool calls appear as tool call spans in your traces, giving you end-to-end visibility into which MCP tools each agent called:

import { withTrace } from '@openai/agents'

const result = await withTrace('mcp-agent-run', async () => {
  return run(researchAgent, userQuery)
})

View traces in the OpenAI dashboard under Traces to see the full reasoning chain including MCP tool invocations.

Production Considerations

Connection pooling: Creating a new MCP client per agent run is expensive. Maintain a pool of connected MCP clients for frequently-used servers.

Tool selection: Large tool counts degrade agent performance. Expose only the MCP tools relevant to each agent's domain rather than all available tools.

Error handling: MCP tool calls can fail if the underlying server is down. Implement fallback behavior in your agent instructions: "If a tool returns an error, acknowledge the limitation and work with available information."

Browse the MCP server directory for tools to add to your OpenAI agents, and see our MCP Server Security Best Practices guide for hardening your production deployment.