GPT-5 MCP Server

A Model Context Protocol (MCP) server that brings OpenAI's GPT-5 capabilities to Claude Code. Features advanced reasoning, cost management, and conversation handling with automatic GPT-4 fallback.

Why Use This?

• Collaborative AI: Combine Claude's capabilities with GPT-5's advanced reasoning
• Cost Control: Built-in spending limits, preflight estimates, per-conversation budgets
• Efficient Context: Context truncation + optional summarization to reduce tokens
• Automatic Fallback: Seamlessly falls back to GPT-4 family with retries/backoff
• File Support: Process PDFs, images, and documents via Claude Code’s @ syntax
• Observability: JSON outputs, usage CSV, optional webhook alerts

Prerequisites

• OpenAI API Key with GPT-5 access (or GPT-4 for fallback)
• Node.js 18+ and pnpm (for local installation)
• Docker (optional, for containerized deployment)
• Claude Code CLI or Claude Desktop

Quick Start

1. Clone and Setup

git clone https://github.com/andreahaku/gpt5_mcp
cd gpt5-mcp
cp .env.example .env
# Edit .env and add: OPENAI_API_KEY=sk-your-key-here

2. Install and Build

pnpm install
pnpm run build

3. Add to Claude Code CLI

Option A: Docker (Recommended)

# Build Docker image
pnpm run docker:build

# Add to Claude Code
claude mcp add gpt5 -s user -- docker run --rm -i --env-file $(pwd)/.env gpt5-mcp:latest

Option B: Local Installation

# Add to Claude Code (replace with your actual path)
claude mcp add gpt5 -s user -- node /path/to/gpt5-mcp/dist/index.js

4. Restart Claude Desktop

Restart Claude Desktop to load the new MCP server.

Alternative: Manual Configuration

Edit your Claude Desktop config file directly:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gpt5": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/.env",
        "gpt5-mcp:latest"
      ]
    }
  }
}

Configuration

Environment Variables

Create a .env file with your OpenAI API key and optional tuning:

# Required
OPENAI_API_KEY=sk-your-api-key-here

# Cost limits (defaults shown)
DAILY_COST_LIMIT=10.00
TASK_COST_LIMIT=2.00

# Reasoning defaults
DEFAULT_TEMPERATURE=0.7
DEFAULT_REASONING_EFFORT=high

# Conversation controls
MAX_CONVERSATION_CONTEXT=10       # messages kept per call
MAX_INSTRUCTION_TOKENS=1500       # truncate very long instructions
CONVERSATION_HARD_CAP_MULTIPLIER=10

# Resource handling
RESOURCE_MAX_TOKENS=1500          # per-resource token budget
RESOURCE_MAX_COUNT=5              # max resources included per call

# OpenAI model and client behavior
OPENAI_RESPONSES_MODEL=gpt-5
OPENAI_FALLBACK_MODELS=gpt-4o,gpt-4o-mini,gpt-4-turbo-preview,gpt-4-turbo,gpt-4,gpt-3.5-turbo
OPENAI_RETRY_COUNT=3
OPENAI_RETRY_BASE_DELAY_MS=300
OPENAI_TIMEOUT_MS=30000

# Alerts
ALERT_WEBHOOK_URL=                # optional URL to POST alerts (JSON)

Available Tools

1. consult_gpt5

Get GPT-5 assistance with advanced reasoning and file support.

Key parameters:

• prompt (required): Your question or task
• reasoning_effort: minimal, low, medium, or high (default: high)
• task_budget: USD limit for this specific task
• max_tokens: hard cap for this response (down-capped by budget)
• stream: enable streaming (server aggregates; client receives final text)

2. start_conversation

Begin a multi-turn conversation with GPT-5.

Parameters:

• topic (required): What the conversation is about
• instructions: Optional system-level guidance
• budget_limit: Optional per-conversation budget (USD)

3. continue_conversation

Continue an existing conversation thread.

Parameters:

• conversation_id (required): ID from start_conversation
• message (required): Your next message
• max_tokens: optional cap for this single turn (down-capped by budget)
• budget_limit: set/override per-conversation budget
• confirm_spending: proceed when near/over budget
• stream: enable streaming (server aggregates; client receives final text)

4. set_conversation_options

Update per-conversation options without sending a message.

Parameters:

• conversation_id (required)
• budget_limit: set/override per-conversation budget
• context_limit: override messages kept in context per call

5. get_cost_report

View usage statistics and costs.

Parameters:

• period: current_task, today, week, or month

6. set_cost_limits

Configure spending limits.

Parameters:

• daily_limit: Maximum daily spending in USD
• task_limit: Maximum per-task spending in USD

Usage Examples

Basic Usage

"Use GPT-5 to help me design a REST API for user authentication"
"Ask GPT-5 to review this code for security issues"

File Analysis

"@config.json Ask GPT-5 to review this for security issues"
"@screenshot.png What UI improvements would GPT-5 suggest?"

Multi-turn Conversations

"Start a GPT-5 conversation about optimizing database queries"
"Continue the conversation: What about indexing strategies?"

Development Commands

# Development
pnpm run dev              # Start with hot reload
pnpm run build            # Compile TypeScript
pnpm test                 # Run tests

# Docker
pnpm run docker:build     # Build Docker image
pnpm run docker:run       # Run in Docker

# Setup
pnpm run install:setup    # Interactive installer
pnpm start               # Choose how to run (menu)

Troubleshooting

Common Issues

Server not appearing in Claude Desktop:

1. Verify config file location (see Alternative: Manual Configuration above)
2. Use absolute paths, not relative paths
3. Restart Claude Desktop completely (Quit → Restart)

API Key Issues:

• Ensure .env file exists with OPENAI_API_KEY=sk-your-key
• Key must start with sk-
• Server will fallback to GPT-4 if GPT-5 is unavailable

Docker Issues:

# Test Docker image
docker run --rm -i --env-file .env gpt5-mcp:latest

# Rebuild if needed
docker build --no-cache -t gpt5-mcp .

Cost Limits:

• Configure limits in .env file
• Use get_cost_report tool to monitor usage
• Daily default: $10, Task default: $2
• For more control, set per-conversation budgets via start_conversation or set_conversation_options.
• The server preflights costs and may ask for confirm_spending=true to proceed when budgets are tight.

Project Structure

gpt5-mcp/
├── src/              # TypeScript source
├── dist/             # Compiled JavaScript
├── data/             # Persistent usage data
├── tests/            # Jest unit tests
└── docs/             # Additional documentation

License

MIT License - see LICENSE file for details

Support

For issues or questions, please open an issue on GitHub.

---

• task_limit: Maximum per-task spending in USD

7. get_conversation_metadata

Return conversation object in JSON (metadata + messages).

8. summarize_conversation

Compress older messages into a concise summary to reduce future token usage.

Parameters:

• conversation_id (required)
• keep_last_n (default 5): number of recent messages to keep verbatim
• max_tokens (default 2000): budget for generating the summary

Note: This server uses OpenAI's GPT-5 Responses API when available and automatically falls back to GPT-4 with adjusted parameters if needed.