Add You.com to OpenAI Codex CLI

Give Codex CLI real-time web search, content extraction, and citation-backed research through the You.com MCP Server.

Quick setup

Add You.com to Codex

Codex reads MCP server config from ~/.codex/config.toml. Add the You.com server — no API key required:

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

This uses our free tier: 100 web searches per day, no signup. Want higher limits and access to you-contents and you-research? See Higher rate limits below.

Start Codex

$ codex

Verify the tools are loaded

Inside Codex, run:

$ /mcp

You should see you-com listed with the you-search tool available. (If you upgrade to API key auth, you-contents and you-research show up too.)

Quick demo

Try these prompts inside Codex:

Search the web for the latest Next.js 15 release notes and summarize the breaking changes.

Find three recent benchmarks comparing Claude Sonnet 4.6 and GPT-5 on coding tasks.

Higher rate limits

For unlimited queries, page-content extraction (you-contents), and deep research (you-research), add an API key. Get one at you.com/platform, then update your config:

1 [mcp_servers.you-com]
2 url = "https://api.you.com/mcp"
3 
4 [mcp_servers.you-com.http_headers]
5 Authorization = "Bearer YDC-YOUR-API-KEY"

Codex TOML gotcha: HTTP headers in Codex’s config.toml go in a separate [mcp_servers.<name>.http_headers] table, not inline. This is different from the JSON headers object used by Claude Code, Cursor, and VS Code.

Local install (no network on startup)

If you’d rather run the MCP server locally via stdio:

1 [mcp_servers.you-com]
2 command = "npx"
3 args = ["-y", "@youdotcom-oss/mcp"]
4 
5 [mcp_servers.you-com.env]
6 YDC_API_KEY = "YDC-YOUR-API-KEY"

Omit the YDC_API_KEY env var to run on the free tier.

Troubleshooting

Codex doesn’t see the tools — run codex --version to confirm you’re on a version with MCP support (0.20+), then restart Codex after editing config.toml.
spawn npx ENOENT (local install only) — install Node.js 18+ and ensure npx is on your PATH, or switch to the remote hosted URL above.
401 / invalid key — regenerate at you.com/platform. Confirm there are no extra spaces around Bearer.
TOML parse errors on headers — headers must be under [mcp_servers.you-com.http_headers], not inline as a JSON-style headers = { ... } object.