How to Add Free Web Search to OpenAI Codex CLI with MCP (No API Key)
OpenAI's Codex CLI is good at reading and changing the code in front of it. When it needs something from the live web, like the newest release of a library, a migration guide, or an error message someone else already solved, you can give it a search tool through an MCP server.
This guide adds web search to Codex CLI with one codex mcp add command. You don't need an API key, an account, or a wallet. We use AgentSearch, which ships as the @agentsearchhq/agentsearch-mcp package on npm and also runs as a free hosted remote MCP server:
Free tier: 25 free searches per IP, then pay per call. No key needed.
What we tested: every codex mcp command and config.toml snippet below was run with codex-cli 0.171.0 on Linux with Node.js 20+, and @agentsearchhq/agentsearch-mcp 1.8.6 (the current npm release). We checked what each command writes to config.toml, what codex mcp list and codex mcp get print, and the tool list each server returns. The Codex config keys come from OpenAI's Codex MCP documentation.
Prerequisites
- Codex CLI installed (
codex --versionshould print a version) and signed in. - Node.js 20 or newer with
npxon your PATH, for the local option. The hosted option needs nothing extra.
Option A: Add the local MCP server (one command)
Run:
codex mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp
Codex replies:
Added global MCP server 'agentsearch'.
What each part does:
agentsearchis the server name. It becomes the[mcp_servers.agentsearch]table in your config.--ends Codex's own options. Everything after it is the command Codex launches, so-ygoes tonpxand not to Codex.npx -y @agentsearchhq/agentsearch-mcpdownloads and starts the server.-yskips npx's install prompt, which a background process can't answer.
The server runs as a local process over stdio. Codex stores the entry in ~/.codex/config.toml:
[mcp_servers.agentsearch]
command = "npx"
args = ["-y", "@agentsearchhq/agentsearch-mcp"]
You can also write that block by hand. The Codex CLI, the Codex IDE extension and the ChatGPT desktop app share this configuration on the same machine, so you set it up once.
Option B: Use the hosted server (no Node.js)
Codex also supports remote MCP servers over the Streamable HTTP transport. AgentSearch runs a free hosted remote MCP server at https://relay.agentsearchhq.com/mcp. Add it with --url:
codex mcp add agentsearch-hosted --url https://relay.agentsearchhq.com/mcp
That writes:
[mcp_servers.agentsearch-hosted]
url = "https://relay.agentsearchhq.com/mcp"
The hosted server needs no sign-in, so there's no codex mcp login step and no bearer token. It has three tools: agentsearch_web_search, agentsearch_extract and agentsearch_render, with the same free limits as the local package. Pick one option. If you add both, Codex sees two copies of the search tool.
Step 2: Check the connection
Outside a session, run:
codex mcp list
You should see your server and its status:
Name Command Args Env Cwd Status Auth
agentsearch npx -y @agentsearchhq/agentsearch-mcp - - enabled Unsupported
The Auth column refers to MCP OAuth. "Unsupported" is normal here because AgentSearch doesn't use OAuth. For one server's details, run codex mcp get agentsearch. Inside the codex TUI, type /mcp to see the active servers.
The local server (Option A) gives Codex these tools:
agentsearch_web_search: web search that returns up to 5 results (title, URL and a snippet). Free, no setup.agentsearch_extract: reads a URL and returns clean markdown or text. Free trial of 5 calls a day per IP, then paid.agentsearch_render: loads a JavaScript-heavy page in a headless browser first, then returns its content. Free trial of 3 calls a day per IP, then paid.agentsearch_search_and_read,agentsearch_news_searchandagentsearch_screenshot: 10 free calls per IP each (lifetime), then paid per call with a wallet (see below).agentsearch_review_lookupandagentsearch_review_submit: read and share agent-written reviews of web tools.
Step 3: Try it
Start codex in your project and ask for something that needs current information:
Search the web for the latest stable release of Vite and tell me if our package.json is behind.
Use agentsearch to find the official migration guide for Express 5, then list the breaking changes that affect src/server.ts.
Find the changelog for the newest TypeScript release and extract the section on breaking changes.
Codex decides when to call the tool. If it doesn't, name the tool in the prompt ("use agentsearch to..."). Search results are snippets. When Codex needs the whole page, it can call agentsearch_extract, or agentsearch_render for pages built with JavaScript.
Useful config.toml options
Codex has per-server options you can add under the same table. These are the ones that matter most here:
[mcp_servers.agentsearch]
command = "npx"
args = ["-y", "@agentsearchhq/agentsearch-mcp"]
startup_timeout_sec = 60
enabled_tools = ["agentsearch_web_search", "agentsearch_extract", "agentsearch_render"]
startup_timeout_secdefaults to 10 seconds. The firstnpxrun downloads the package, which can take longer, so 30 to 60 gives it room.enabled_toolsis an allow list. The example keeps only the three tools that have a free tier.tool_timeout_sec(default 60) limits how long one tool call can run.enabled = falseturns a server off without deleting it.
Project scope. To share the setup with a repo, put the same table in .codex/config.toml at the project root. Codex reads project config only for trusted projects.
Optional: paid search, Extract and Render with a wallet
When you need more than the free allowance, the local server can pay per call in USDC on Base over x402, with no account and no API key. Paid calls go to AgentSearch's direct x402 API: search and news $0.003, extract $0.002, search + read $0.005. See pricing for every tool. Calls are settled only after a successful answer.
Use a new, dedicated wallet that holds only a small amount of USDC. The wallet setup guide walks through it. With release 1.8.x, a wallet key turns on the paid tools, and search stays free unless you also set AGENTSEARCH_MODE=paid.
Don't paste the key into config.toml. Codex's env_vars option forwards a variable from the environment that starts Codex, so the key stays in your shell:
[mcp_servers.agentsearch-paid]
command = "npx"
args = ["-y", "@agentsearchhq/agentsearch-mcp"]
env_vars = ["AGENTSEARCH_WALLET_PRIVATE_KEY"]
startup_timeout_sec = 60
[mcp_servers.agentsearch-paid.env]
AGENTSEARCH_MAX_TOTAL_ATOMIC = "50000"
Then export AGENTSEARCH_WALLET_PRIVATE_KEY=0x... in the shell where you start codex. The [mcp_servers.agentsearch-paid.env] table sets fixed values. codex mcp add can write those too, with --env KEY=VALUE before the --:
codex mcp add agentsearch-paid --env AGENTSEARCH_MAX_TOTAL_ATOMIC=50000 -- npx -y @agentsearchhq/agentsearch-mcp
Spend caps. The server checks these before it signs anything:
AGENTSEARCH_MAX_TOTAL_ATOMICcaps total spend per server session, in USDC atomic units (1000000 = $1.00). The default is $1.00; the example sets $0.05.AGENTSEARCH_MAX_PER_CALL_ATOMIClowers the per-call ceiling (the default ceiling is $0.020).
When a cap is reached, the tool returns a message saying nothing was signed instead of paying.
Troubleshooting
The server times out on the first start. The first npx run downloads the package. Set startup_timeout_sec = 60 on the server, or run npx -y @agentsearchhq/agentsearch-mcp once in a terminal to warm the npm cache. A healthy server prints a "listening on stdio" line to stderr and waits (Ctrl+C to stop).
npx: command not found or an engine error. Codex launches the command with the PATH it sees. Install Node.js 20+ and start codex from a shell where node -v works. With nvm or similar tools, the shell matters.
The tool isn't in /mcp. Check codex mcp list: is the server enabled? Did you restart the session after editing config.toml? For a project-scoped .codex/config.toml, is the project trusted?
Extract or Render says a wallet is needed. The free trial for the day is used up (5 extracts, 3 renders per IP), or you set AGENTSEARCH_FREE_TRIAL=0. Nothing was charged. Add a wallet server or wait for the next day.
Search says it needs payment. The 25 free searches for your IP are used up. Add a wallet and set AGENTSEARCH_MODE=paid, or call the direct x402 API from your own code.
Remove a server. codex mcp remove agentsearch.
FAQ
Do I need an API key to add web search to Codex CLI?
No. codex mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp needs no key, account or wallet. You get 25 free searches per IP, then pay per call.
Does Codex CLI support remote MCP servers?
Yes. Codex supports Streamable HTTP servers with a url in config.toml, and codex mcp add <name> --url <URL> writes that for you. AgentSearch's hosted server is https://relay.agentsearchhq.com/mcp and needs no authentication.
Where does Codex store MCP servers?
In ~/.codex/config.toml under [mcp_servers.<name>], or in a project's .codex/config.toml for trusted projects. The Codex CLI, IDE extension and ChatGPT desktop app share it.
How do I pass a wallet key without writing it to config.toml?
Use env_vars = ["AGENTSEARCH_WALLET_PRIVATE_KEY"] on the server and export the variable in the shell that starts Codex. Use a dedicated wallet with a small balance and a spend cap.
How much do paid calls cost?
On the direct x402 API: search and news $0.003, extract $0.002, search + read $0.005 per call, in USDC on Base. See the pricing page for every tool.
Is it safe to let Codex read web pages?
Treat web content as untrusted input. A page can contain text written to steer an AI. Keep Codex's approval prompts on for commands and file edits, and review what it proposes after reading external pages.
Get started
Run codex mcp add agentsearch -- npx -y @agentsearchhq/agentsearch-mcp, check it with codex mcp list, and ask Codex about something that changed last week. No Node.js? Use the hosted remote MCP server instead. Using Claude Code too? See How to Add Free Web Search to Claude Code with MCP. Setup for other clients is on the MCP page.
More from the blog
- How to Add Free Web Search to Claude Code with MCP (No API Key)
- Free Remote MCP Server for Web Search: Hosted, No Install, No API Key
- How to Add Free Web Search to Cursor with MCP (No API Key)
- How to Add Web Search to an OpenAI Agents SDK Agent (No API Key)
- Add Web Search to Your AI Agent with MCP (2026 Guide)
Service pages: Web Search API · Web Extract API · Web Render API