# 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**