openai-web-mcp
Provides live web search and page reading by calling OpenAI's ChatGPT backend codex/alpha/search endpoint (the one behind Codex's web.run). Exposes tools for web search (with result limits, domain allow/block filters, recency, extra queries, and country/city localization) and page fetching (line-based paging, in-page find, token budgets, plus a direct-fetch HTML-to-text fallback). Also handles the ChatGPT device-code login lifecycle and reports login/usage status.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
openai-web-mcp
A remote MCP server on Cloudflare Workers that gives Claude (or any MCP client) live web search and page reading through your ChatGPT login. It calls chatgpt.com/backend-api/codex/alpha/search, the endpoint behind the Codex CLI's own web.run tool. Background, evidence and live probe results: hermes-reverse-engineering/findings/05-openai-search-for-claude.md.
Tool | Replaces | Upstream command |
| WebSearch |
|
| WebFetch |
|
| — | Kite-style sign-in: returns a link + one-time code; call again to confirm |
| — | login state, relay state (awake / waking), today's usage |
src/index.ts OAuth provider (/authorize, /oauth/*), /mcp, /admin, /health, cron
src/auth.ts owner-passphrase consent (from the YouTube Research worker), per-kind login rate limits
src/vault.ts TokenVault Durable Object: own device-code login, single-flight refresh, cron keep-fresh
src/codex.ts alpha/search client + output cleanup (cite markers, 【n†link】, Lnn: lines, paging)
src/relay.ts free-tier relay handling: /health check, RELAY_WARMING fail-fast, background wake-up, pre-warm
src/service.ts search/fetch orchestration, daily cap, 401→refresh→retry once, direct-fetch fallback
src/url.ts SSRF guard for user-supplied URLs
src/admin.ts owner pages: ChatGPT sign-in, status, /admin/reachability
reachability/ throwaway, binding-free probe worker (`npm run reachability`)
relay/ dependency-free egress relay for Render (POST /alpha/search only, shared secret)
scripts/smoke.mjs live OAuth + MCP check against the deployed Worker (`--live` adds a search and a fetch)Login lifecycle (how ChatGPT login expiry is handled)
stateDiagram-v2
[*] --> signed_out
signed_out --> pending: chatgpt_login / admin "Sign in"
expired --> pending: chatgpt_login
pending --> signed_in: owner enters code at auth.openai.com/codex/device
pending --> signed_out: 15 min without approval
signed_in --> signed_in: refresh (≤5 min to expiry, 401, or daily cron if <2 days left or 8+ days since refresh)
signed_in --> expired: refresh rejected permanently (401, invalid_grant, refresh_token_expired / reused / invalidated)
signed_in --> pending: chatgpt_login force=true (old tokens keep serving until approval)Access-token expiry (routine): refreshed automatically, one refresh at a time. Users see nothing.
Refresh token dead (password change, "log out all devices", revoked, reused, idle too long): the vault moves to
expiredwith the reason. Every tool then returnsLOGIN_REQUIREDwith anext_stepthat tells Claude to callchatgpt_login. Claude shows you the link and code; you approve on your phone or laptop; Claude callschatgpt_loginagain to confirm.web_fetchkeeps working through the direct fallback in the meantime.Transient refresh errors (5xx, other 400s) keep the login and are retried on the next call, matching Codex.
Proactive refresh: the daily cron refreshes when under 2 days remain or the last refresh is 8+ days old (Codex's
TOKEN_REFRESH_INTERVAL), so an unused server doesn't let the grant go stale.You only find out about an expiry when a tool is called or you open
/admin. There is no push alert yet.
Related MCP server: WebChatMCP.js
The relay's cold start (Render free plan)
Render spins a free service down after 15 minutes without traffic, and waking it takes about a minute (Render docs; measured 26 s). A tool call that waits that long can time out in the client, so the Worker never waits for it:
Fail fast: before each search the Worker asks the relay's
/health(about 100 ms when awake; an awake answer is trusted for 10 minutes). If it doesn't answer within 8 s, the Worker starts the wake-up in the background and returnsRELAY_WARMINGwithretry_after_seconds: 30. Nothing is counted againstDAILY_LIMIT.Agent instructions: the server instructions and the
web_searchdescription tell the agent to tell the user, wait about 30 s and retry that one call once, without loops or parallel retries.web_fetchkeeps working: while the relay wakes it falls back to a direct fetch, with a note saying so.Pre-warm: any authenticated
/mcprequest (connecting, listing tools,web_status) wakes a sleeping relay in the background, so it is usually awake before the first search.web_statusalso reportsrelay.state(warm/waking).No keep-alive pinging: that would burn the workspace's 750 free Render instance hours, which ValuePickr and google-health also use.
Security model
/mcprequires OAuth (mcp:read). The consent page asks forOWNER_PASSPHRASE./adminuses HTTP Basic auth: userowner, passwordOWNER_PASSPHRASE. Only failed attempts count toward the 20-per-hour limit.The ChatGPT tokens live only in the
TokenVaultDurable Object. The Worker does its own device-code login, so it never copies~/.codex/auth.json. Refresh tokens are single-use, and sharing one would sign your Codex CLI out.It identifies itself as
originator: openai-web-mcp. It never impersonates the Codex CLI.web_fetchblocks private, loopback, link-local and metadata hosts. Theglobal_fetch_strictly_publiccompatibility flag enforces the same at runtime.DAILY_LIMIT(default 400) caps upstream calls per UTC day.
Deploy
npm installnpx wrangler loginnpm run reachabilityThen open http://localhost:8799 and expect "verdict": "REACHABLE"; a JSON 401 from alpha/search is the good case. If it says BLOCKED_OR_ERROR with challenged: true, Cloudflare bot management is blocking Worker egress to chatgpt.com. See the Render fallback in the findings doc, §6.
npx wrangler d1 create openai-web-mcpnpx wrangler kv namespace create OAUTH_KVPaste both ids into wrangler.jsonc, then:
npx wrangler d1 migrations apply openai-web-mcp --remoteopenssl rand -base64 36 | npx wrangler secret put OWNER_PASSPHRASEStore that passphrase in your password manager before piping it (or generate it there and paste it at the prompt).
npm test && npx wrangler deployThen open https://openai-web-mcp.gmathur1993.workers.dev/admin and choose Sign in with ChatGPT. Enter the code it shows at auth.openai.com/codex/device. After that, /admin/reachability?live=1 runs one real search.
Use it from Claude
Claude Code:
claude mcp add --transport http openai-web https://openai-web-mcp.gmathur1993.workers.dev/mcpThen make Claude use these tools instead of the built-in ones, in ~/.claude/settings.json:
{ "permissions": { "deny": ["WebSearch", "WebFetch"] } }Claude Desktop / claude.ai: add the same /mcp URL as a custom connector and turn off the built-in web search toggle.
Develop
npm run checknpm testThe integration tests run the built Worker in miniflare against a fake OpenAI (device login, refresh race, 401 retry, fallback, SSRF, daily cap). Miniflare listens on a local port. In the Claude Code sandbox that needs sandbox.network.allowLocalBinding: true.
Configuration reference
Server settings (wrangler.jsonc vars / secrets)
Setting | Values | Current | Why |
| ≥ 32 chars | you generate it | Gates MCP consent and |
| URL |
| OAuth issuer and resource must equal the deployed origin. |
| ≥ 1 upstream calls per UTC day |
| Protects your ChatGPT quota. Plan limits for |
| any string; not validated (a made-up id gave identical results) |
| The field is required. A real Codex id keeps working if OpenAI starts validating it. |
| ISO-3166 alpha-2 / city / IANA tz; unset = global |
| Big effect: "filter coffee near me" went from global blogs to Bengaluru cafés and Swiggy. |
| comma list, ≤ 100 hosts | unset | Always-excluded sites ( |
cron | cron expr |
| Token keep-fresh + table cleanup. |
| URL / secret ≥ 32 chars | Render relay / Worker secret | Unset |
| ≥ 0 ms | 8000 | How long |
| ≥ 0 s | 600 | How long an awake answer is trusted. Render sleeps after 900 s idle, so 600 leaves margin. |
Tool parameters (Claude sets per call)
Tool · param | Range | Default | Notes |
| 1–400 chars | — | |
| 1–20 | 8 | Sets the token budget: |
| ≤ 5 hosts | none | Per-query |
| ≤ 20 hosts | none | Merged with |
| 1–3650 | none | Per-query |
| ≤ 3 | none | Upstream allows at most 4 queries per call. |
| ISO-2 or | server default | A per-call country replaces the default city and timezone. |
| public http(s) | — | Private, loopback and metadata hosts are refused. |
| ≥ 0 | 0 | Pass |
| 1–200 chars | none | Returns the window around matches. |
| 1000–12000 | 6000 | About 4 chars per token, so ~24k chars per page window. |
| bool | false |
|
Upstream request fields (fixed in code)
Field | Values | Sent | Why |
|
|
| Codex maps |
|
| not sent | No visible difference live; |
|
|
| What Codex sends. |
| approximate {country, city, region, timezone} | from config/tool | Verified: strong localisation. |
| ≤ 100 hosts | from config/tool | Verified. |
| ≤ 100 hosts | not used | Very strict live (1 result); the per-query |
| int | search: | Controls both output size and result count. |
| string | search: random UUID; fetch: UUID from SHA-256(url) | Same |
Internal constants
Constant | Value | Why |
Refresh skew | 300 s | Codex refreshes 5 min before expiry (Hermes uses 120 s). |
Refresh interval | 8 days | Codex |
Keep-fresh margin | 2 days | The cron refreshes early, so a daily run never misses expiry. |
Login code window | 15 min | Hermes waits 15 min for device approval. |
Poll interval | max(3 s, server | Hermes floor. |
Wake-up request | up to 70 s | Background request that wakes the relay (Render documents ~60 s). |
Upstream timeout | 60 s | Hermes |
Fallback fetch | 20 s, 4 redirects, 3 MB, HTML/text only | Bounded Worker CPU and memory. |
Login attempt limits | consent 10/h/IP; admin failures 20/h/IP | Brute-force protection. |
MCP OAuth tokens | access 1 h, refresh 30 days (idle 30 days) | Clients re-authorise monthly if unused. |
Status
Deployed 2026-11-10; see DEPLOYMENT.md. chatgpt.com blocks Cloudflare Workers' egress IPs (findings §12), so the Worker sends its one alpha/search call through a stateless relay on Render's free plan (relay/, findings §14). Login, token storage, OAuth and the tools all stay on Cloudflare.
Known limits
alpha/searchis undocumented and unversioned, and OpenAI can change or remove it.Signed in with the owner's main ChatGPT account (owner's choice, 2026-11-10). Searches share that account's usage limits, and any action OpenAI takes over use of the undocumented endpoint would hit that account. Keep
DAILY_LIMITconservative.Searches count against your ChatGPT plan limits. Verified working on a free plan, 2026-11-10.
finance(not exposed as a tool) has no Indian equities.linenowindows start on upstream chunk boundaries. The Worker trims to your requestedlineand returnsnext_line.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted Web Crawler MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Live AI-native web search with citations. One tool for every MCP client. Flat per-request pricing.
Web search, data extraction and controlled browser automation for AI assistants via OAuth.
Web search, page reading, site crawling, data extraction and cited research. OAuth sign-in.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to perform keyless web searches, extract fully rendered pages into clean Markdown, and automate a shared Chrome browser through page navigation, clicking, typing, reading, screenshots, and backtracking—all without API keys.MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to drive ChatGPT's web interface through a built-in persistent browser, requiring only a single manual login. Prompts are sent through temporary incognito chats and the captured answer text is returned as tool results, along with live model listing, login/status probing, and optional HTTP transport.83Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables ChatGPT to perform read-only web, news, multi-query, page extraction, and GitHub searches through OAuth-protected remote MCP tools running on Cloudflare Workers.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to run SearXNG-backed public web searches and Crawl4AI page extraction for approved domains, with local approvals, deny rules, audit history, and optional OpenAI Secure MCP Tunnel connectivity.Apache 2.0