GPT-5 Search MCP Server

An MCP (Model Context Protocol) server that provides access to OpenAI's GPT-5 model with web search and advanced reasoning capabilities.

Features

• GPT-5 Integration: Direct access to OpenAI's latest GPT-5 reasoning model

• Web Search: Built-in web search capabilities for up-to-date information

• Type Safety: Full TypeScript types with Zod validation for API responses

• Error Handling: Robust error handling with retry logic and structured error messages

• Multiple Variants: Different tools for various use cases:

  • gpt5-search: Main tool with web search and medium reasoning

  • gpt5: Pure reasoning without web search

  • gpt5-low: Fast responses with low reasoning effort

  • gpt5-high: Deep analysis with high reasoning effort

  • gpt5-mini: Using the smaller gpt-5-mini model

  • gpt5-nano: Using the smallest gpt-5-nano model

  • gpt5-pro: ⚠️ EXPENSIVE - Premium GPT-5 Pro model (use only when explicitly requested)

Related MCP server: MCP OpenAI Tools

Limitations

⚠️ No Local File Access: This MCP server does not provide file reading capabilities. The GPT-5 tools cannot access or read local files from your system. Only text prompts are sent to the OpenAI API.

• What it CAN do: Write gpt5-pro outputs to files, make web searches, perform reasoning

• What it CANNOT do: Read local files, access your filesystem, include file contents in prompts

If you need to provide file contents to GPT-5, you must copy/paste the content into your prompt manually.

Installation

npm install
npm run build

Configuration

Set your OpenAI API key as an environment variable:

export OPENAI_API_KEY=your-api-key-here

Optional environment variables:

• SEARCH_CONTEXT_SIZE: Controls web search context size (low, medium, high). Default: medium

• REASONING_EFFORT: Controls reasoning effort (low, medium, high). Default: medium

• CLIENT_CWD: Directory where gpt5-pro outputs will be saved. Default: server's current working directory

Usage with Claude Code

Add to your Claude Code configuration (.claude/config.json):

{
  "mcpServers": {
    "gpt5-search": {
      "command": "node",
      "args": ["/path/to/gpt5-search-mcp/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here",
        "CLIENT_CWD": "${workspaceFolder}"
      }
    }
  }
}

Note: The CLIENT_CWD variable controls where gpt5-pro output files are saved. Use ${workspaceFolder} to save files in your current working directory, or specify an absolute path.

Available Tools

gpt5-search

Main tool with web search capabilities. Best for queries requiring current information.

gpt5

Pure reasoning without web search. Best for complex problem-solving that doesn't need current data.

gpt5-low

Fast responses with low reasoning effort and web search. Good for simple queries.

gpt5-high

High reasoning effort with web search. Best for complex problems requiring deep analysis.

gpt5-mini

Uses the gpt-5-mini model - smaller, faster, and less expensive.

gpt5-nano

Uses the gpt-5-nano model - smallest and fastest for simple queries.

gpt5-pro ⚠️

EXPENSIVE MODEL - Use Only When Explicitly Requested

Uses the gpt-5-pro-2025-10-06 model with maximum reasoning capabilities and web search. This is a premium, high-cost model that provides the most advanced reasoning and analysis capabilities.

Important Notes:

• This model should only be invoked when the user explicitly requests it due to its significantly higher cost

• Automatic File Output: Due to extremely large output sizes that can crash clients, gpt5-pro responses are automatically saved to files in the gpt5-pro-outputs/ directory

• The tool returns only a preview (first 1000 chars) and the file path

• Files are named with timestamps: gpt5-pro-YYYY-MM-DDTHH-MM-SS-mmmZ.txt

• Output location can be controlled with the CLIENT_CWD environment variable

Implementation Details

Architecture Improvements (v0.0.2)

• Tool Factory Pattern: Single createTool function eliminates code duplication

• Configuration Registry: Centralized toolConfigs object manages all tool variants

• Type Safety: Zod schemas validate API responses with proper TypeScript inference

• Error Handling:

  • Custom HttpError class for structured errors

  • Automatic retry with exponential backoff for transient failures

  • Respects Retry-After headers for rate limiting

  • User-friendly error messages for different status codes

API Response Format

The GPT-5 API returns a structured response with:

• Reasoning tokens (hidden but billed)

• Web search calls (if web search is enabled)

• Final message with text and URL citations

Testing

Run the test script to verify the server is working:

node test-mcp.js

License

WTFPL - Do What The Fuck You Want To Public License