config.toml, or with the plugin listing Codex shares with ChatGPT. The MCP route takes your own API key, so use it on a paid tier. It also needs a second step: turning off the built-in search.
Install
Add the server
Add the following to~/.codex/config.toml:
X-API-Key header, not an environment variable. Codex doesn’t read KEENABLE_API_KEY for a remote server. Create one in the console; see Authentication.
To try Keenable in Codex with no key, use the keyless URL and leave out the http_headers line:
/mcp URL. /mcp publishes OAuth discovery metadata, which can make Codex start a browser sign-in instead of connecting. /mcp-public publishes none. See Keyless endpoint for listings and presets.
Turn off the built-in search
Codex enables web search by default for local chats, incached mode, where results come from an index OpenAI maintains rather than a live fetch. Set web_search to disabled to remove that tool. Codex then uses search_web_pages for every lookup.
web_search is a top-level key, so put it above the [mcp_servers.keenable] line. A bare key written after a table header belongs to that table. Below the header, it becomes mcp_servers.keenable.web_search, which Codex ignores without an error. The finished file:
The mode key takes four values:
cached (the default), indexed, live, and disabled. A full-access sandbox (--yolo or danger-full-access) upgrades cached to live without telling you, so a permissive session searches the live web whether or not you asked for it.Don’t confuse the mode with the [tools.web_search] table, which carries settings like allowed_domains and context_size and does not switch the tool off. Older releases used [tools] web_search = true and then [features] web_search_request = true; both are deprecated in favour of the top-level key.codex --profile research. A profile is its own file, ~/.codex/research.config.toml, which Codex layers over config.toml. The key stays top-level there:
Tell the agent which tool to use
Codex readsAGENTS.md for project instructions, and ~/.codex/AGENTS.md applies everywhere. Name the tools there even with the built-in search disabled. Codex loads MCP tool schemas on demand: it sees only a tool’s name and description until it decides the tool is relevant. Add this rule to AGENTS.md:
Verify
Run/mcp in the TUI to confirm the server connected and both tools are listed, then ask something that needs the live web. Codex should call search_web_pages without being told to.
If Codex still doesn’t call Keenable, check codex --version. Releases before v0.121.0 registered on-demand tool names in a format their own lookup table didn’t match, so Codex never called any MCP server’s tools. Update Codex to fix it.
Plugins Directory
Keenable is also published in OpenAI’s Plugins Directory, the catalog Codex shares with ChatGPT. Install it from the listing and sign in through OAuth. There’s no key to paste. Keenable meters usage against the organization of the account you connect, so it shares the rate limits and pricing of every API key the organization has issued: 100,000 free requests a month, then $4 per 1,000. The same listing covers ChatGPT. The built-in search competes with the plugin exactly as it does with the MCP server, so theweb_search change above is worth making on either route.
Keenable SELECT is a second Keenable plugin in the same directory. It’s a separate server that answers a question with one SQL query over live web results and returns a table. See SELECT for both routes into it.
→ Full MCP server reference
Related pages
Cursor
Add Keenable to Cursor over MCP with one click, an mcp.json entry or the Keenable CLI, and turn off Cursor’s own web search.
Gajae-Code
Use Keenable as the web search provider in Gajae-Code (gjc), the coding-agent harness, with providers.webSearch set to keenable. No key needed.
DeepSeek Harness
Keenable web search and page fetch for DeepSeek Harness’s built-in web_search and web_fetch tools, with any model and no API key.
Claude
Add Keenable to Claude and Claude Code, and keep Claude’s own web search from competing with it.