gpt5mcp

MCP server for OpenAI GPT-5 API integration with Claude Code. Provides gpt5_agent and gpt5_codex tools.

Setup

Option A: npm install (recommended)

npm install -g gpt5mcp

# Basic (gpt5_agent only)
claude mcp add gpt5mcp -e OPENAI_API_KEY=sk-... -- gpt5mcp

# Full (with gpt5_codex support)
claude mcp add gpt5mcp \
  -e OPENAI_API_KEY=sk-... \
  -e CODEX_BIN=$(which codex) \
  -- gpt5mcp

Option B: From source

git clone https://github.com/cristip73/gpt5mcp.git
cd gpt5mcp
npm install
npm run build

claude mcp add gpt5mcp \
  -e OPENAI_API_KEY=sk-... \
  -e CODEX_BIN=$(which codex) \
  -- node /absolute/path/to/gpt5mcp/build/index.js

Option C: Manual config

Create/edit ~/.claude/.mcp.json:

{
  "mcpServers": {
    "gpt5mcp": {
      "command": "gpt5mcp",
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "CODEX_BIN": "/path/from/which/codex"
      }
    }
  }
}

Codex CLI Setup (for gpt5_codex tool)

The gpt5_codex tool requires OpenAI's Codex CLI. Skip this if you only need gpt5_agent.

# Install Codex CLI
npm install -g @openai/codex

# Find the path
which codex
# Example output: /usr/local/bin/codex

# Use this path for CODEX_BIN

Verify

Restart Claude Code and check:

claude mcp list

You should see gpt5mcp with tools gpt5_agent and gpt5_codex.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENAI_API_KEY | Yes | OpenAI API key with GPT-5 access | | CODEX_BIN | No | Path to Codex CLI binary (for gpt5_codex tool) |

Active Tools

GPT-5 Agent (gpt5_agent)

Autonomous agent with SSE streaming that solves complex multi-step tasks. Supports tool orchestration, web search, code interpreter, and file operations.

Key Parameters: | Parameter | Default | Description | |-----------|---------|-------------| | task | required | Task description | | model | gpt-5.2 | Model: gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, gpt-5-nano | | reasoning_effort | medium | none, minimal, low, medium, high | | verbosity | medium | low, medium, high | | max_iterations | 10 | Max agent loops (1-20) | | enable_web_search | true | Enable web search | | enable_code_interpreter | false | Enable code execution | | enable_file_operations | false | Enable file read/write | | save_to_file | true | Save output to gpt5_docs/ | | previous_response_id | - | Continue previous conversation |

Examples:

{
  "task": "Research the latest AI developments in 2026",
  "reasoning_effort": "high",
  "enable_web_search": true
}

{
  "task": "Analyze this Python code for performance issues",
  "file_path": "/path/to/code.py",
  "enable_code_interpreter": true
}

GPT-5 Codex (gpt5_codex)

Deep code analysis via Codex CLI. Spawns codex binary for autonomous code editing.

Key Parameters: | Parameter | Default | Description | |-----------|---------|-------------| | prompt | required | Task for Codex | | model | gpt-5.2-codex | Model: gpt-5.2-codex, gpt-5.1-codex, o3, o4-mini | | reasoning | medium | low, medium, high, extra_high | | edit_mode | auto_edit | research, auto_edit, full_auto, dangerous | | file_path | - | Single file input (100KB max) | | files | - | Multiple files (200KB total) | | output_format | standard | standard (with metadata) or clean |

Edit Modes:

• research - Read-only analysis, no file changes
• auto_edit - Prompts before each edit
• full_auto - Auto-applies safe edits
• dangerous - No restrictions (use with caution)

Example:

{
  "prompt": "Refactor this module to use async/await",
  "file_path": "/path/to/module.ts",
  "reasoning": "high",
  "edit_mode": "auto_edit"
}

Inactive Tools

Disabled by default for performance. Enable in src/tools/index.ts:

| Tool | Description | |------|-------------| | web_search | Web search via OpenAI Responses API | | file_operations | File read/write/delete | | code_interpreter | Execute Python/JavaScript | | image_generation | DALL-E 3 / GPT-Image-1 | | function_definition | Define custom reusable functions |

To enable:

// src/tools/index.ts
const ACTIVE_TOOLS = {
  gpt5_agent: true,
  gpt5_codex: true,
  image_generation: true,  // ← set to true
  // ...
};

Then: npm run build and restart Claude Code.

Architecture

src/
├── index.ts              # MCP server entry point
├── utils.ts              # GPT-5 API utilities
├── types/
│   ├── responses.ts      # API response types
│   └── tools.ts          # Tool interface definitions
└── tools/
    ├── index.ts          # Tool registration & activation
    ├── registry.ts       # Tool registry (singleton)
    ├── base.ts           # Base tool class
    └── built-in/
        ├── gpt5-agent.ts     # ✅ Active
        ├── gpt5-codex.ts     # ✅ Active
        ├── web-search.ts
        ├── file-operations.ts
        ├── code-interpreter.ts
        ├── image-generation.ts
        └── function-definition.ts

Streaming Implementation

GPT-5 Agent uses SSE (Server-Sent Events) to prevent MCP timeout:

• Activity timeout: 120 seconds without data
• Request timeout: up to 15 minutes for complex tasks
• Activated when reasoning_effort is not none or minimal

Troubleshooting

Server not found:

claude mcp remove gpt5mcp
claude mcp add gpt5mcp -e OPENAI_API_KEY=sk-... -- gpt5mcp

Socket hang up errors:

• Ensure .mcp.json points to build/index.js (not dist/)
• SSE streaming handles long-running requests

Codex not working:

# 1. Install Codex CLI
npm install -g @openai/codex

# 2. Find path
which codex

# 3. Re-add MCP with correct path
claude mcp remove gpt5mcp
claude mcp add gpt5mcp -e OPENAI_API_KEY=sk-... -e CODEX_BIN=$(which codex) -- gpt5mcp

Credits

Originally inspired by AllAboutAI-YT. Significantly rewritten with SSE streaming, Codex CLI integration, and improved tool architecture.

Built with MCP • Powered by OpenAI GPT-5