OpenAI o3 Search MCP server

The o3-search-mcp server enables AI coding agents to use OpenAI's advanced models with web search capabilities. By connecting this MCP server to your AI agent, you can access powerful models like GPT-5 and o4-mini to solve complex problems by searching the web and leveraging OpenAI's reasoning abilities.

Installation Options

Using npx (Recommended)

For Claude Code users:

$ claude mcp add o3 \
	-s user \
	-e OPENAI_MODEL=o3 \
	-e OPENAI_API_KEY=your-api-key \
	-e SEARCH_CONTEXT_SIZE=medium \
	-e REASONING_EFFORT=medium \
	-e OPENAI_API_TIMEOUT=300000 \
	-e OPENAI_MAX_RETRIES=3 \
	-- npx o3-search-mcp

For JSON configuration:

{
  "mcpServers": {
    "o3-search": {
      "command": "npx",
      "args": ["o3-search-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_MODEL": "o3",
        "SEARCH_CONTEXT_SIZE": "medium",
        "REASONING_EFFORT": "medium",
        "OPENAI_API_TIMEOUT": "300000",
        "OPENAI_MAX_RETRIES": "3"
      }
    }
  }
}

Local Installation

If you prefer to run the server locally:

git clone [email protected]:yoshiko-pg/o3-search-mcp.git
cd o3-search-mcp
pnpm install
pnpm build

For Claude Code users:

$ claude mcp add o3 \
	-s user \
	-e OPENAI_MODEL=o3 \
	-e OPENAI_API_KEY=your-api-key \
	-e SEARCH_CONTEXT_SIZE=medium \
	-e REASONING_EFFORT=medium \
	-e OPENAI_API_TIMEOUT=300000 \
	-e OPENAI_MAX_RETRIES=3 \
	-- node /path/to/o3-search-mcp/build/index.js

For JSON configuration:

{
  "mcpServers": {
    "o3-search": {
      "command": "node",
      "args": ["/path/to/o3-search-mcp/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_MODEL": "o3",
        "SEARCH_CONTEXT_SIZE": "medium",
        "REASONING_EFFORT": "medium",
        "OPENAI_API_TIMEOUT": "300000",
        "OPENAI_MAX_RETRIES": "3"
      }
    }
  }
}

Configuration Options

Environment Variable	Options	Default	Description
OPENAI_API_KEY	Required	-	OpenAI API Key
OPENAI_MODEL	Optional	o3	Model to use (options: o3, o4-mini, gpt-5)
SEARCH_CONTEXT_SIZE	Optional	medium	Controls search context size (options: low, medium, high)
REASONING_EFFORT	Optional	medium	Controls reasoning effort (options: low, medium, high)
OPENAI_API_TIMEOUT	Optional	300000	API timeout in milliseconds
OPENAI_MAX_RETRIES	Optional	3	Maximum retries for failed requests

Usage Examples

Debugging Help

When you're stuck with hard-to-solve errors:

> I'm getting the following error on startup, please fix it. If it's too difficult, ask o3.
> [Paste error message here]

> The WebSocket connection isn't working. Please debug it. If you don't know how, ask o3.

Library Documentation

Get information about libraries even when documentation is lacking:

> I want to upgrade this library to v2. Proceed while consulting with o3.

> I was told this option for this library doesn't exist. It might have been removed. Ask o3 what to specify instead and replace it.

Complex Design Tasks

Use the model as a design partner:

> I want to create a collaborative editor, so please design it. Also, ask o3 for a design review and discuss if necessary.

Important Note

To use the o3 model from the OpenAI API, you need to either upgrade to tier 4 or verify your organization. Using an API key that isn't enabled for o3 will result in errors. For more information, visit OpenAI's documentation.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "o3-search" '{"command":"npx","args":["o3-search-mcp"],"env":{"OPENAI_API_KEY":"your-api-key","SEARCH_CONTEXT_SIZE":"medium","REASONING_EFFORT":"medium"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "o3-search": {
            "command": "npx",
            "args": [
                "o3-search-mcp"
            ],
            "env": {
                "OPENAI_API_KEY": "your-api-key",
                "SEARCH_CONTEXT_SIZE": "medium",
                "REASONING_EFFORT": "medium"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "o3-search": {
            "command": "npx",
            "args": [
                "o3-search-mcp"
            ],
            "env": {
                "OPENAI_API_KEY": "your-api-key",
                "SEARCH_CONTEXT_SIZE": "medium",
                "REASONING_EFFORT": "medium"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect