OpenAI Agents MCP 🤖

A Model Context Protocol (MCP) server that bridges OpenAI's Agents SDK with Claude Code and other MCP clients. Enable powerful AI agent capabilities including web search, file search, and computer use directly in your development environment.

🚀 Quick Start

npx openai-agents-mcp

That's it! The server will start and be ready to accept MCP connections.

🎯 Features

🔍 Web Search - Search the web using OpenAI's integrated web search capability
📁 File Search - Analyze and search through files with AI-powered understanding
💻 Computer Use - Interact with computer interfaces (preview feature, requires tier 3-5)
⚡ Real-time Streaming - Stream responses for better user experience
🔧 Claude Code Ready - Works seamlessly with Claude Code via stdio transport
🧪 Test-Driven - Comprehensive test suite with high coverage
📦 NPX Compatible - Run directly without installation

📋 Prerequisites

Node.js 18.0.0 or higher
OpenAI API key
For computer use: OpenAI usage tier 3-5

🔧 Installation & Setup

Option 1: NPX (Recommended)

No installation needed! Just run:

npx openai-agents-mcp

Option 2: Global Installation

npm install -g openai-agents-mcp
openai-agents-mcp

Option 3: From Source

git clone https://github.com/merlinrabens/openai-agents-mcp.git
cd openai-agents-mcp
npm install
npm run build
npm start

⚙️ Configuration

Environment Variables

Create a .env file in your project root:

# Required
OPENAI_API_KEY=sk-...your-key-here

# Optional
OPENAI_ORGANIZATION=org-...         # Your org ID
ENABLE_COMPUTER_USE=true            # Enable computer use (requires tier 3-5)
LOG_LEVEL=info                      # debug | info | warn | error

Claude Code Integration

Add to your Claude Code configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "openai-agents": {
      "command": "npx",
      "args": ["openai-agents-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...your-key-here"
      }
    }
  }
}

Then restart Claude Code to activate the server.

💡 Usage Examples

Once configured, you can use these commands in Claude Code:

Web Search

Use the web_search tool to find the latest news about AI developments

File Search

Use the file_search tool to analyze this codebase and find all API endpoints

Computer Use (if enabled)

Use the computer_use tool to take a screenshot of the current screen

🏗️ Architecture

┌─────────────┐     MCP Protocol     ┌──────────────┐     OpenAI API     ┌──────────┐
│ Claude Code │ ◄──────────────────► │  This Server │ ◄─────────────────► │  OpenAI  │
│   or other  │      stdio/HTTP       │              │    Agents SDK       │  Agents  │
│ MCP Client  │                       │              │                     │          │
└─────────────┘                       └──────────────┘                     └──────────┘

Key Components

MCP Server Core - Handles MCP protocol using @modelcontextprotocol/sdk
OpenAI Integration - Uses @openai/agents SDK for agent capabilities
Tool Translation - Maps MCP tool calls to OpenAI function calls
Stream Handler - Manages real-time streaming responses
Error Handler - Provides retry logic and graceful error handling

🧪 Development

Setup Development Environment

# Clone the repository
git clone https://github.com/merlinrabens/openai-agents-mcp.git
cd openai-agents-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

Available Scripts

npm run dev          # Development mode with hot reload
npm test            # Run test suite
npm run test:watch  # Run tests in watch mode
npm run test:coverage # Generate coverage report
npm run build       # Build for production
npm run lint        # Run ESLint
npm run format      # Format with Prettier

Project Structure

src/
├── server/         # MCP server implementation
│   └── index.ts    # Main server class
├── openai/         # OpenAI Agents SDK integration
│   └── client.ts   # OpenAI client wrapper
├── tools/          # Tool definitions
├── config/         # Configuration management
└── utils/          # Utilities and helpers

tests/              # Test suite
bin/               # CLI entry point
examples/          # Usage examples

📊 Testing

The project follows Test-Driven Development (TDD) principles:

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Coverage report
npm run test:coverage

Current test coverage: ~71%

💰 Pricing

This server uses OpenAI's API, which has the following pricing (as of March 2025):

Input: $3 per 1M tokens
Output: $12 per 1M tokens
Computer Use: Research preview (requires tier 3-5)

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests first (TDD approach)
Implement your feature
Ensure all tests pass
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built with:

Model Context Protocol SDK - The MCP protocol implementation
OpenAI Agents SDK - OpenAI's agent framework
Claude Code - Anthropic's AI-powered development environment

🐛 Troubleshooting

Server won't start

Ensure OPENAI_API_KEY is set correctly
Check Node.js version is 18.0.0 or higher
Run npm run build if running from source

Claude Code doesn't see the server

Restart Claude Code after updating configuration
Check the configuration file path is correct
Verify the server starts without errors: npx openai-agents-mcp

Computer use not working

Verify your OpenAI account is tier 3-5
Set ENABLE_COMPUTER_USE=true in environment

📧 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Author: Merlin Rabens

🚦 Status

✅ Web Search - Fully functional
✅ File Search - Fully functional
⚠️ Computer Use - Preview (requires tier 3-5)
🚧 OpenAI Agents SDK - Preview as of March 2025

Note: The OpenAI Agents SDK is currently in preview. Features and pricing may change. The deprecated Assistants API will be sunset by mid-2026 in favor of the Agents SDK.