MCP OpenAI Server

A Model Context Protocol (MCP) server that lets you seamlessly use OpenAI's models right from Claude.

Features

• Direct integration with OpenAI's chat and planning models
• Support for multiple models including:
  • gpt-4o (chat)
  • gpt-4o-mini (chat)
  • o1-preview (planning)
  • o1-mini (planning)
  • o1 (advanced planning)
  • o3-mini (lightweight planning)
• Reasoning effort levels (low, medium, high)
• Simple message passing interface
• Basic error handling

Prerequisites

• Node.js >= 18 (includes npm and npx)
• Claude Desktop app
• OpenAI API key

Installation

First, make sure you've got the Claude Desktop app installed and you've requested an OpenAI API key.

Add this entry to your claude_desktop_config.json (on Mac, you'll find it at ~/Library/Application\ Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-openai-planner": {
      "command": "npx",
      "args": ["-y", "@edwardtang1024/mcp-openai-planner@latest"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here (get one from https://platform.openai.com/api-keys)"
      }
    }
  }
}

This config lets Claude Desktop fire up the OpenAI MCP server whenever you need it.

Usage

Leverage the multi-agent architecture inspired by grapeot's planner-executor design to optimize both reasoning quality and cost efficiency:

Claude as Executor, o1 as Planner

The MCP server implements a streamlined multi-agent workflow where:

• Claude (3.7 Sonnet) automatically functions as your Executor agent
• o1/o1-mini/o3-mini serves as your dedicated Planner agent

This eliminates the need to manually switch roles - each model plays to its strengths:

# Just ask o1 for planning help directly
@o1 I need to design a system that processes large volumes of customer data while ensuring privacy compliance.

# Claude acts as the executor, o1 responds as the planner

Automatic Executor-to-Planner Request Formatting:

When you use the openai_plan tool with any o1 model, your message is automatically formatted as an executor request:

# Your simple input
@o1 How should I approach building a secure authentication system?

# Gets automatically formatted as
[EXECUTOR REQUEST]
Task: Project planning/implementation
Status: Seeking guidance
Question: How should I approach building a secure authentication system?

Please analyze this request and provide guidance on the next steps.

Structured Requests for Better Planning:

For more complex planning needs, you can use explicit request formatting:

@o1
Task: Implement OAuth2 authentication
Status: Blocked
Progress: Basic login flow implemented
Blocker: Unsure about token management strategy
Question: Should we use short-lived JWTs with refresh or longer expiration?
Context: Currently storing tokens in localStorage

Cost-Optimized Multi-Agent Workflow:

# Phase 1: Planning (o1 - $0.15/1k tokens)
- Problem decomposition
- Architecture design
- Risk assessment

# Phase 2: Implementation (Claude 3.7 - $0.03/1k tokens)
- Code writing
- Testing
- Documentation

# Phase 3: Targeted Planning (o3-mini - $0.015/1k tokens)
- Specific implementation questions
- Code optimization advice
- Cost-effective reasoning

Key Benefits of This Architecture:

• 💸 90% Cost Reduction: Use o1 only for critical planning decisions
• 🤖 Automatic Role Assignment: No need to explicitly switch between roles
• 🔄 Contextual Prompting: Messages automatically formatted for planning
• ⚡ Faster Development: Models specialized for their most efficient tasks

Supported Models

The server currently supports these models:

• gpt-4o (default)
• gpt-4o-mini
• o1-preview
• o1-mini
• o1
• o3-mini

Example Commands

# Basic planning request
@o1 How should we structure the database for a multi-tenant SaaS app?

# Planning with explicit task context
@o1
Task: Implement real-time notification system
Status: Starting implementation
Question: What's the best approach for handling WebSocket connections at scale?

# Cost-efficient targeted planning
@o3-mini
Task: Optimize API response times
Status: In progress
Context: Current response time is 1.2s for listing endpoints
Question: Which indexes should I add to improve query performance?

# Using different models for specific strengths
@gpt-4o Can you help me debug this React component?
@o1 Design a scalable architecture for this microservice

Tools

1. openai_chat

   • Sends messages to OpenAI's chat completion API
   • Arguments:
     • messages: Array of messages (required)
     • model: Which model to use (optional, defaults to gpt-4o)

2. openai_plan

   • Specialized tool for complex reasoning tasks and inter-agent communication
   • Arguments:
     • messages: Array of messages with developer role support (required)
     • model: Planning model to use (o1-preview, o1-mini, o1, o3-mini)
     • reasoning_effort: Cognitive effort level (low/medium/high, defaults to low)

Problems

This is alpha software, so may have bugs. If you have an issue, check Claude Desktop's MCP logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Development

# Install dependencies
pnpm install

# Build the project
pnpm build

# Watch for changes
pnpm watch

# Run in development mode
pnpm dev

Requirements

• Node.js >= 18
• OpenAI API key

Verified Platforms

• macOS
• [x ] Linux

License

MIT

Authors

• edwardtang 🛠️ Current maintainer
  Building upon the foundations of:
  • mzxrai 🚀 Original MCP Server (mcp-openai)
  • grapeot 🤖 Multi-agent Architecture (devin.cursorrules)

🙏 Grateful for the open source community's collective wisdom that made this project possible.