How to Add a Web Search Plugin to Codex CLI with the You.com MCP Server

TLDR: Codex CLI gets web search through the Model Context Protocol, not a built-in browser. You add the You.com MCP server with a short TOML block in your Codex config, point a bearer-token environment variable at your API key, restart Codex, and the search tool appears alongside its other tools. This guide covers the config for both the authenticated and keyless server, how to verify the plugin actually connected, the scoping options Codex supports, and the failure modes that leave a server silently dead.

Codex CLI is OpenAI's coding agent that runs in your terminal. Its tool surface is extensible through MCP, the same open protocol that other coding agents speak, which means the wiring you add for Codex is the same pattern as our Claude Code web search setup. You.com runs an MCP server that exposes live web search, and this guide connects it to Codex. The MCP concepts and the you-search tool itself are covered in What Is MCP Web Search?

What Does Codex Support for MCP?

Codex stores MCP server configuration in config.toml, at ~/.codex/config.toml by default, with project-scoped servers living in .codex/config.toml for trusted projects, per OpenAI's Codex MCP documentation (fetched October 2026). Each server is a [mcp_servers.<name>] table. Codex supports two server kinds: STDIO servers, launched from a local command, and Streamable HTTP servers, reached at a URL. For HTTP servers, the options that matter here are url, required, and bearer_token_env_var, which names an environment variable holding the token to send in the Authorization header. Codex also supports per-server tool allow lists and approval modes, which you will use to scope the plugin.

How Do You Add the You.com MCP Server?

You.com runs its MCP server as a Streamable HTTP server at https://api.you.com/mcp, with a keyless variant at https://api.you.com/mcp?profile=free that needs no key. Append one table to ~/.codex/config.toml:

[mcp_servers.youcom]
url = "https://api.you.com/mcp"
bearer_token_env_var = "YOUCOM_API_KEY"

Set the variable in the shell that launches Codex, because Codex resolves the environment variable at connection time:

export YOUCOM_API_KEY="your key goes here"

For a keyless start, the free profile needs no token:

[mcp_servers.youcom_free]
url = "https://api.you.com/mcp?profile=free"

The keyless profile is an evaluation surface: expect the authenticated profile with your own API key to be the production path.

How Do You Verify the Plugin Is Live?

Three checks, in order of strength. First, ask Codex a question that requires the live web and watch it call the search tool, the only end-to-end proof. Second, check the connection: in the ChatGPT desktop app, typing /mcp lists connected servers and their auth state, per the Codex docs. Third, scope the tools once connected, so the server only contributes what you want:

[mcp_servers.youcom]
url = "https://api.you.com/mcp"
bearer_token_env_var = "YOUCOM_API_KEY"
enabled_tools = ["you-search"]
default_tools_approval_mode = "prompt"

The enabled_tools allow list and default_tools_approval_mode are per-server Codex options from the configuration reference (fetched October 2026). Approval mode prompt keeps a human confirm each tool use, which is the right default while you are trusting a new server.

When Should You Use MCP Instead of Calling the API in Code?

The decision framework is one question: is the search for the agent's interactive session, or is it part of software you are shipping? MCP is the right surface when Codex, running interactively, needs live facts to write correct code, because the tool call, approval, and result all stay inside the session. Direct API calls are the right surface when the search happens in code that must run without an agent, a pipeline, a service, or a test, because shipping software that depends on an agent session is a fragility choice. Our guide to adding web search to agent tool calling covers the direct-API side of that line.

Why Would the Server Silently Not Work?

Each failure mode has a detection. Missing environment variable: the variable is set in a different shell than the one launching Codex, or set after Codex started, so the token resolves empty and auth fails. Detection: launch Codex fresh from the shell where you exported the variable, and confirm with echo $YOUCOM_API_KEY in that same shell. Config scope surprise: the server is defined in a project .codex/config.toml that Codex does not trust, so it loads nothing. Detection: put the server in ~/.codex/config.toml and confirm it appears, then decide whether the project scope is worth the trust step. Stale config after edit: Codex reads MCP config at startup, so edits do nothing until restart. Detection: any config change gets followed by a restart before you conclude the config is wrong. Wrong server name in a login: codex mcp login takes the server name exactly as it appears in the TOML table, so codex mcp login youcom works and codex mcp login you.com does not. Detection: the login command's error text names the server it cannot find, which is the name to copy.

Related Guides

FAQ

Does Codex have built-in web search? Codex's tool surface is extensible through MCP, and OpenAI's documentation describes MCP as the way to connect Codex to external tools and context. For live web results, adding an MCP search server is the supported path, which is exactly what this guide wires up.

Is the You.com MCP server free? The server runs in two profiles: an authenticated profile using your You.com API key, and a keyless free profile for getting started. Usage terms and limits live on the You.com side and can change, so treat the free profile as an evaluation surface and the authenticated profile as the production path.

Where is the config file on Windows and macOS? The Codex documentation places the user-level config at ~/.codex/config.toml regardless of platform, which resolves to your home directory. Project-scoped servers go in .codex/config.toml inside the project, and Codex only trusts them in projects you have marked trusted.

Can I scope the server so it only provides search? Yes. Codex supports enabled_tools and disabled_tools per server, so an allow list of you-search keeps the server to the search tool, and default_tools_approval_mode controls whether tool use needs your approval each time.

Why does my API key work in curl but not in Codex? Almost always the environment variable. Codex resolves bearer_token_env_var in its own process environment, so the variable must be exported in the shell that launches Codex, and exporting it in another terminal or afterward does nothing. Restart Codex from the exporting shell and the two paths converge.