OpenAI Agents MCP Server

Overview

The OpenAI Agents MCP Server provides a bridge between OpenAI's Agents SDK and the Model Context Protocol (MCP). It allows AI agents to use OpenAI's multi-agent orchestration capabilities through standard MCP tools, enabling seamless integration with any MCP-compatible client.

This server exposes OpenAI's agent handoff system, guardrails, and tool calling as MCP tools, making it easy to build multi-agent workflows within any MCP ecosystem.

Features

• Agent handoff — Structured handoff between agents
• Guardrails integration — Policy-based safety controls
• Tool calling — Full OpenAI function calling support
• Session management — Persistent conversation state
• Multi-agent orchestration — Complex agent workflows
• MCP 2.0 support — Latest MCP protocol features
• TypeScript and Python — Dual-language support
• Real-time streaming — SSE-based streaming responses

Installation

Quick Setup

# Install via npm
npm install -g @openai/agents-mcp

# Or via pip
pip install openai-agents-mcp

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "openai-agents": {
      "command": "openai-agents-mcp",
      "args": ["serve"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Docker Setup

docker run -d \
  -e OPENAI_API_KEY=your-api-key \
  -p 3000:3000 \
  openai/agents-mcp:latest

Setup

1. Get an OpenAI API Key

   • Sign up at platform.openai.com
   • Create an API key in your account settings

2. Set Environment Variables

   export OPENAI_API_KEY="your-api-key-here"
   export MCP_TRANSPORT="stdio"
   

3. Start the Server

   openai-agents-mcp serve
   

Available Tools

Tool	Description
create_agent	Create a new agent with instructions
handoff_to	Hand off to another agent
run_agent	Run an agent with input
add_guardrail	Add a guardrail to an agent
add_tool	Add a tool to an agent
session_create	Create a new session
session_get	Get session state
session_update	Update session state
run_workflow	Run a multi-agent workflow
get_trace	Get trace for debugging

Usage Examples

Create an Agent

{
  "name": "create_agent",
  "arguments": {
    "name": "researcher",
    "instructions": "You are a research assistant. Find information and summarize it.",
    "model": "gpt-4o"
  }
}

Run an Agent

{
  "name": "run_agent",
  "arguments": {
    "agent_name": "researcher",
    "input": "Research the latest developments in AI agents",
    "max_tokens": 1000
  }
}

Handoff Between Agents

{
  "name": "handoff_to",
  "arguments": {
    "from_agent": "researcher",
    "to_agent": "writer",
    "context": "Research findings: AI agents are becoming more autonomous."
  }
}

Add a Guardrail

{
  "name": "add_guardrail",
  "arguments": {
    "agent_name": "researcher",
    "guardrail": {
      "type": "input_filter",
      "patterns": ["internal", "confidential"],
      "action": "block"
    }
  }
}

Create a Session

{
  "name": "session_create",
  "arguments": {
    "id": "user-session-123",
    "store": "redis",
    "ttl": 3600
  }
}

Advanced Features

Multi-Agent Workflow

{
  "name": "run_workflow",
  "arguments": {
    "agents": ["researcher", "analyst", "writer"],
    "input": "Research and write a report on AI agents",
    "max_handoffs": 3,
    "timeout": 300
  }
}

Guardrails with Policies

{
  "name": "add_guardrail",
  "arguments": {
    "agent_name": "researcher",
    "guardrail": {
      "type": "policy",
      "policy": {
        "allowed_tools": ["search", "fetch"],
        "blocked_patterns": ["internal", "secret"],
        "max_tokens": 2000
      }
    }
  }
}

Session Management

{
  "name": "session_update",
  "arguments": {
    "id": "user-session-123",
    "state": {
      "last_agent": "researcher",
      "progress": "Research complete",
      "next_step": "Analyze findings"
    }
  }
}

Integration with AI Agents

Claude Code Integration

# In Claude Code, use OpenAI Agents MCP tools
> Create a researcher agent
> Run the agent to research AI trends
> Hand off to a writer agent

Multi-Agent Workflow Example

# Example workflow using OpenAI Agents MCP
async def research_and_write(topic: str):
    # Create agents
    await create_agent("researcher", "Research assistant", model="gpt-4o")
    await create_agent("writer", "Content writer", model="gpt-4o")
    
    # Run workflow
    result = await run_workflow(
        agents=["researcher", "writer"],
        input=f"Research and write about: {topic}",
        max_handoffs=2
    )
    
    return result.final_output

Pros

• ✅ Official OpenAI integration
• ✅ Full multi-agent orchestration
• ✅ Guardrails and safety controls
• ✅ Session management
• ✅ MCP 2.0 support
• ✅ Real-time streaming
• ✅ TypeScript and Python support

Cons

• ❌ Requires OpenAI API key
• ❌ OpenAI ecosystem lock-in
• ❌ Pricing based on OpenAI usage
• ❌ No native multi-provider support
• ❌ Limited without OpenAI subscription

When to Use

• Building multi-agent workflows with OpenAI
• Need OpenAI's latest models and features
• Want guardrails and safety controls
• Integrating OpenAI Agents SDK with MCP
• Building production agent systems
• Need session management and tracing

Resources

• OpenAI Agents SDK Docs
• MCP Documentation
• GitHub Repository
• OpenAI Platform