openai_websearch

Self-hostable MCP server (official @modelcontextprotocol/sdk) and reusable API client that exposes OpenAI's native server-side web search via the ChatGPT/Codex Responses API.

No API keys required. Authenticate with your ChatGPT account in 3 ways:

1. Browser OAuth — gets a URL, you click Connect (works on any device)
2. Device-code flow — URL + code for headless/remote machines (no browser needed)
3. Existing Codex auth — auto-falls back to ~/.codex/auth.json

Tokens auto-refresh — no manual re-login every few weeks.

Features

Capability	Description
web_search	Full-text web search with real URLs and citations
image_search	Image search returning web image URLs and source pages
Built-in OAuth login	node index.js login or --device-code — no Codex install needed
Auto-refreshing tokens	refresh_token grant, stores in ~/.openai-websearch/auth.json
Official MCP SDK	@modelcontextprotocol/sdk — proper protocol handshake, Zod schemas, JSON Schema output
Reusable library	Import in any Node/Bun/Deno project
Zero API keys	Uses your ChatGPT subscription

---

As an MCP server

Install & authenticate

git clone https://github.com/hffmnnj/openai_websearch.git
cd openai_websearch
npm install

# Authenticate (browser flow — prints a URL)
node index.js login

# Or headless (prints URL + code, enter on any device)
node index.js login --device-code

# Check auth status
node index.js auth-status

Configure your MCP client

{
  "mcpServers": {
    "openai_websearch": {
      "command": "node",
      "args": ["/path/to/openai_websearch/index.js"]
    }
  }
}

Tools

Tool	Args	Description
web_search	query (required), context_size (low/medium/high), model	Text web search with real URLs
image_search	query (required), context_size, model	Image search returning URLs + source pages

---

As a library (NPM package)

Install

npm install github:hffmnnj/openai_websearch

Quick start

import { search, imageSearch } from 'openai_websearch';

// Web search
const results = await search('smart ring market size 2026');
console.log(results.text);
console.log(results.searchQueries);  // queries OpenAI actually ran
console.log(results.usage);          // token counts

// Image search
const images = await imageSearch('oura ring product photos');
console.log(images.text);            // URLs and descriptions

Explicit auth (no Codex, no login prompt — pass tokens directly)

import { createClient } from 'openai_websearch';

const client = createClient({
  accessToken: 'eyJhbG...',     // JWT from your own OAuth flow
  refreshToken: 'rt.1.AAB...',  // auto-refreshes when expired
  accountId: 'uuid-here',
});

const result = await client.search('test query');

Full OAuth in your own code

import { authenticateBrowser, authenticateDeviceCode, createClient } from 'openai_websearch';

// Browser flow
const { tokens, authorizeUrl } = await authenticateBrowser();
// → user opens authorizeUrl, clicks Connect

// Device-code flow (headless)
const { tokens, verificationUrl, userCode } = await authenticateDeviceCode();
// → user visits verificationUrl, enters userCode

// Then use the tokens
const client = createClient({
  accessToken: tokens.access_token,
  refreshToken: tokens.refresh_token,
});

API reference

search(query, opts?) / client.search(query, opts?)

Param	Type	Default	Description
query	string	required	What to search for
opts.contextSize	'low' | 'medium' | 'high'	'medium'	Web context to retrieve
opts.model	string	'gpt-5.6-luna'	OpenAI model

Returns { text, searchQueries, usage, model }.

createClient(opts?)

Param	Type	Default	Description
opts.authPath	string	~/.openai-websearch/auth.json	Auth file location
opts.accessToken	string	—	Explicit JWT
opts.refreshToken	string	—	Auto-refresh when expired
opts.accountId	string	—	ChatGPT account ID
opts.fallbackToCodex	boolean	true	Fall back to ~/.codex/auth.json
opts.model	string	'gpt-5.6-luna'	Default model

Auth helpers (from openai_websearch/auth)

Export	Description
authenticateBrowser({ timeoutMs })	PKCE browser flow, callback on localhost:1455
authenticateDeviceCode({ pollInterval, timeoutMs })	Headless flow, returns URL + code
refreshTokens(refreshToken)	Refresh grant
AuthManager	Load/refresh/save token management

---

Configuration

Env var	Default	Description
OPENAI_WEBSEARCH_AUTH_FILE	~/.openai-websearch/auth.json	Auth file path
OPENAI_WEBSEARCH_MODEL	gpt-5.6-luna	Default model
CODEX_AUTH_PATH	~/.codex/auth.json	Fallback Codex auth file

Requirements

• Node.js 18+ (native fetch), Bun, or Deno
• A ChatGPT account (free/plus/pro — whatever you have)
• No Codex CLI required (unless you want the fallback auth)

How it works

1. Auth: OAuth2 with PKCE against auth.openai.com (same client as Codex CLI). Browser flow or device-code flow. Tokens stored locally, refreshed automatically via refresh_token grant.
2. Search: Sends requests to the ChatGPT backend Responses API (chatgpt.com/backend-api/codex/responses) with the web_search tool.
3. MCP: The server uses the official @modelcontextprotocol/sdk — proper JSON-RPC framing, protocol version negotiation, Zod → JSON Schema derivation, argument validation.

All search runs server-side at OpenAI — same infrastructure that powers ChatGPT's web search.

License

MIT