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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests first (TDD approach)
4. Implement your feature
5. Ensure all tests pass
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. 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.