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_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_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

For local installs, install Node.js 18+ and ensure npx is on your PATH, or switch to the remote hosted URL above.

401 or 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.

Resources

MCP Server Reference

Endpoint, authentication, and full tool reference.

SDKs & Tools Overview

Browse every You.com SDK, agent tool, and integration.