# 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)
```bash
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
```bash
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`:
```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`.
```bash
# 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:
```bash
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:**
```json
{
"task": "Research the latest AI developments in 2026",
"reasoning_effort": "high",
"enable_web_search": true
}
```
```json
{
"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:**
```json
{
"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:**
```typescript
// 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:**
```bash
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:**
```bash
# 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](https://github.com/AllAboutAI-YT). Significantly rewritten with SSE streaming, Codex CLI integration, and improved tool architecture.
---
**Built with MCP • Powered by OpenAI GPT-5**
