> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/ai/connect/codex.md). # Codex Install the Currents plugin in the Codex CLI or the Codex app and sign in, or add the Currents MCP server with codex mcp add for the IDE extension Currents is listed in the Codex plugin directory as [Currents](https://chatgpt.com/plugins/plugin_asdk_app_6abc73667f608191b7511e1375170326). Install it in the Codex CLI or the Codex app and sign in to Currents, and Codex can read your runs, test results, failure evidence and analytics. There is no server URL to enter. The plugin brings the [Currents MCP server skills](/ai/agent-skills/agent-skill-currents-mcp.md) with it: `fix-failing-tests`, `collect-evidence` and `browser-evidence`. Codex knows those workflows without being told. Codex and [ChatGPT](/ai/connect/chatgpt.md) share one plugin directory, so the same Currents plugin is the one to install in both. ## Install the Currents plugin {% tabs %} {% tab title="Codex CLI" %} 1. Run `codex`, then enter `/plugins`. 2. Find **Currents** and install it. 3. Start a new session, then [sign in](#sign-in) when Codex asks you to connect. {% endtab %} {% tab title="Codex app" %} 1. In the Codex app or the ChatGPT desktop app, open the **Plugins** tab. 2. Find **Currents** and select the plus button. 3. When Codex asks you to connect, [sign in](#sign-in). 4. Start a new chat. {% endtab %} {% endtabs %} The Codex IDE extension does not support plugins. For the IDE extension, [add the server by URL](#add-the-server-by-url). ## Sign in A browser window opens. Sign in to Currents, choose the organization Codex will work in, and approve the permissions it asks for. See [Sign in once](/ai/connect.md#sign-in-once) for what each screen shows. Codex renews the connection on its own from then on. To revoke it everywhere, remove it under **Account → Connected Applications** in Currents. ## Check the connection Type `/mcp` inside a `codex` session to see the active servers. Then ask something only Currents can answer: > Which tests in `` were flakiest on main this week, and why? ## Add the server by URL Add the server with `codex mcp add` in these cases: * You use the Codex IDE extension, which does not support plugins. * You sign in to Codex with an OpenAI API key instead of a ChatGPT account. With an API key, the plugin directory offers only plugins that do not need an OAuth sign-in, and Currents does. * You want to share the server with everyone working in a repository. ```bash codex mcp add currents --url https://mcp.currents.dev/mcp ``` This writes an entry to `~/.codex/config.toml`: ```toml [mcp_servers.currents] url = "https://mcp.currents.dev/mcp" ``` The Codex CLI, the Codex IDE extension and the ChatGPT desktop app read the same configuration, so the entry makes Currents available in all three. To share the server with everyone working in a repository, put the same table in `.codex/config.toml` at the repository root instead. Codex reads project configuration from trusted projects only. The file holds no credential: each person signs in as themselves. Then sign in: ```bash codex mcp login currents ``` Run `codex mcp list` to see the configured servers. ### Ask before writes Every Currents tool says whether it only reads. Have Codex ask you before any tool that does not: ```toml [mcp_servers.currents] url = "https://mcp.currents.dev/mcp" default_tools_approval_mode = "writes" ``` With this, Codex runs the read tools on its own and stops for writes such as `currents-delete-run`, which permanently deletes a run. `enabled_tools` and `disabled_tools` narrow the list further. See the [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp). ### Use an API key instead For a CI job or anywhere no one can complete the browser sign-in, send a Currents [API key](/dashboard/administration/api-keys.md) from an environment variable: ```bash codex mcp add currents --url https://mcp.currents.dev/mcp \ --bearer-token-env-var CURRENTS_API_KEY ``` ```toml [mcp_servers.currents] url = "https://mcp.currents.dev/mcp" bearer_token_env_var = "CURRENTS_API_KEY" ``` A key acts as the organization, not as a person. See [Connect with an API key](/ai/connect/remote.md#connect-with-an-api-key) for what a key can reach and how to revoke it. ### If you added the server by URL before A server you added with `codex mcp add` keeps working. Installing the plugin as well gives Codex two Currents connections. To move to the plugin, run `codex mcp remove currents`, then [install the Currents plugin](#install-the-currents-plugin). Keep the entry if you also use the IDE extension. ## Troubleshooting | What you see | What to do | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | No Currents in `/plugins` | Check that you signed in to Codex with a ChatGPT account. With an API key, [add the server by URL](#add-the-server-by-url). | | Currents tools fail with `401` | Reinstall the plugin and sign in again. For a server added by URL, run `codex mcp login currents`. | | The wrong organization's data | Revoke the connection in Currents, sign in again, and choose the other organization. | For other errors, see [Troubleshooting](/ai/connect.md#troubleshooting). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.currents.dev/ai/connect/codex.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.