# Codex CLI

> Connect MCP Bond to the OpenAI Codex CLI.

Requires [Codex CLI 0.147.0 or later](#codex-version).

## Quick setup

Follow the current, tested steps on [the Codex CLI setup page](https://docs.valency.io/guides/chatgpt/codex-cli/). The sections below cover additional cases and troubleshooting.

**Prefer to set it up yourself?**

**Already connected?** Run `codex mcp list`. If `valency` is listed, skip the add command and verify it with a real `list_sources` tool call. If not, check `codex plugin list` too: a previously installed Valency plugin may already provide the MCP connection. Use that connection instead of adding a duplicate.

1. Add Valency from a terminal if it is absent:

   ```bash
   codex mcp add valency --url https://mcp.valency.io/
   ```

   This saves the connection for future Codex CLI sessions.

2. Complete **one** browser sign-in. If the add command opens Valency sign-in, finish it and wait for the command to succeed. Only if sign-in did not start or finish, run:

   ```bash
   codex mcp login valency
   ```

   A Valency account is created automatically on first sign-in. You do not need an API token, client ID, or secret, and your Valency email does not have to match your ChatGPT email.

3. Start a new Codex CLI session so it loads the connection, then ask it to call `list_sources` **on the MCP server named `valency`**. A returned source list confirms it works. Seeing Valency in `codex mcp list` or `/mcp` only confirms configuration. An account-wide `codex_apps/valency` result does not verify this CLI connection.

4. Ask [(more prompt ideas)](https://docs.valency.io/reference/examples.md):

   > Use Valency to search for papers about quantum computing

:::tip[What success looks like]
You see paper results in your terminal, with sources you can inspect.
:::

## Troubleshooting

<a id="codex-version"></a>

**Sign-in fails with "Authorization server response missing required issuer"?**
Your Codex CLI is too old. Run `codex --version` to check: versions 0.143.0 through 0.146.x cannot finish Valency sign-in, even after you approve it in the browser. Run `codex update` (or upgrade through npm or Homebrew) to get 0.147.0 or later, then run `codex mcp login valency`.

**Need to sign in again?**
Run `codex mcp login valency`, complete browser sign-in, then retry `list_sources`.

**Tools don't appear?**
Run `codex mcp get valency` to check the saved server, then start a new Codex CLI session. MCP tools may not load into a session that was already open when you added the server.

**Need to start over with a direct connection?**
Run `codex mcp remove valency`, then follow the add and sign-in steps above. This removes the directly configured server; a Valency plugin, if you have one, is managed separately.

---

## Need help?

If something isn't working, check [Troubleshooting](https://docs.valency.io/help/troubleshooting.md) for common fixes. See the [FAQ](https://docs.valency.io/help/faq.md) for general questions, or [report an issue](https://docs.valency.io/help/reporting-issues.md) if you're still stuck.