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