> For clean Markdown of any page, append `.md` to the page URL.
> Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL).
> Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key).
> Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing.
> OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`.

# 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](https://github.com/youdotcom-oss/agent-skills). 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](/docs/agents/docs-mcp-server) for setup and examples.

## Install the Plugin

## Add the Marketplace and Install

```bash
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.

## Sign In and Start a Session

Codex prompts you to authenticate when you install the plugin. Then start a new session so Codex loads the plugin:

```bash
codex
```

## Try It

Codex invokes skills with a `$` mention:

```text
$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:

```toml
[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](#higher-rate-limits) below. `you-research` and `you-finance` need `/mcp/research`, `/mcp/finance`, or an explicit allowlist.

## Start Codex

```bash
codex
```

## Verify the Tools Are Loaded

Inside Codex, run:

```bash
/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:

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

```text
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](https://you.com/platform), then update your config. `you-research` and `you-finance` still need `/mcp/research`, `/mcp/finance`, or an explicit allowlist:

```toml
[mcp_servers.you-com]
url = "https://api.you.com/mcp"

[mcp_servers.you-com.http_headers]
Authorization = "Bearer <YDC_API_KEY>"
```

> **Warning**
>
> **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:

```toml
[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](https://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](/docs/agents/mcp-server)

Endpoint, authentication, and full tool reference.

#### [SDKs & Tools Overview](/docs/integrations-overview)

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