Which integrations are available for this server?

Integrates OpenAI's GPT-5 models and Codex CLI to provide autonomous agents for multi-step task execution, web search capabilities, and advanced code analysis and refactoring.

How do I use gpt5mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gpt5mcp refactor this module to use async/await and optimize performance" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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.

gpt5mcp

gpt5mcp

Setup

Option A: npm install (recommended)

Option B: From source

Option C: Manual config

Codex CLI Setup (for `gpt5_codex` tool)

Verify

Environment Variables

Active Tools

GPT-5 Agent (`gpt5_agent`)

GPT-5 Codex (`gpt5_codex`)

Inactive Tools

Architecture

Streaming Implementation

Troubleshooting

Credits

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

gpt5mcp

Setup

Option A: npm install (recommended)

Option B: From source

Option C: Manual config

Codex CLI Setup (for gpt5_codex tool)

Verify

Environment Variables

Active Tools

GPT-5 Agent (gpt5_agent)

GPT-5 Codex (gpt5_codex)

Inactive Tools

Architecture

Streaming Implementation

Troubleshooting

Credits

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

Codex CLI Setup (for `gpt5_codex` tool)

GPT-5 Agent (`gpt5_agent`)

GPT-5 Codex (`gpt5_codex`)