Add You.com to OpenAI Codex CLI

The You.com plugin for Codex installs five skills and MCP server configs for the default, research, and finance endpoints from the agent-skills repo. The skills tell Codex when to use each You.com tool and how to cite what it finds.

Install our docs MCP server

This documentation ships with a Docs MCP Server that gives any MCP-enabled agent a searchDocs tool to search every page here and get back relevant passages with source URLs—no API key required. Point your client at https://you.com/docs/_mcp/server. See the Docs MCP Server guide for setup and examples.

Install the Plugin

Add the Marketplace and Install

codex plugin marketplace add youdotcom-oss/agent-skills
codex plugin add you@you-com

You can also install from inside a Codex session: run /plugins, find you in the you-com marketplace, and enable it.

Try It

Codex invokes skills with a $ mention:

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

Included Skills

Skill	Use it for
`you-web`	Current web search and URL reading, with sources cited
`you-research`	Choosing between agent-led searching and a single cited `you-research` call
`you-finance`	Finance questions through the `you-finance` tool
`you-discover`	Finding the right You.com API, MCP server, or SDK for a project you’re building
`you-free`	Keyless `you-search` and `you-discover` through the free MCP profile

Use the MCP Server Without the Plugin

To add only the tools, without the skills, configure the MCP server directly.

Add You.com to Codex

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

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

This uses our free profile: keyless you-search and you-discover, 100 queries per day, no signup. Want higher limits and you-contents? See Higher rate limits below. you-research and you-finance need /mcp/research, /mcp/finance, or an explicit allowlist.

Start Codex

codex

Verify the Tools Are Loaded

Inside Codex, run:

/mcp

You should see you-com listed with you-search and you-discover. (An API key on /mcp adds you-contents and you-balance. you-research and you-finance need the dedicated paths or an explicit allowlist.)

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 higher limits plus you-contents and you-balance on /mcp, add an API key. Get one at you.com/platform, then update your config. you-research and you-finance still need /mcp/research, /mcp/finance, or an explicit allowlist:

[mcp_servers.you-com]
url = "https://api.you.com/mcp"
[mcp_servers.you-com.http_headers]
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:

[mcp_servers.you-com]
command = "npx"
args = ["-y", "@youdotcom-oss/mcp"]
[mcp_servers.you-com.env]
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.