> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Codex

> Connect OpenAI Codex to Control Plane through the AI Plugin, the ChatGPT Plugin directory, or a direct MCP registration.

<Tip>
  We recommend the [Control Plane AI Plugin](/ai/plugin) for Codex. It configures the MCP server on the `core` toolset profile and adds skills, agents, slash commands, and guardrails on top.
</Tip>

## Pick your Codex surface

Codex ships three clients, and how you connect Control Plane differs by surface:

| Surface | Control Plane AI Plugin | ChatGPT Plugin directory | Direct MCP registration |
| - | - | - | - |
| **Codex CLI** | Yes, `codex plugin marketplace add` | Yes, through `/plugins` | Yes, `codex mcp add` |
| **Codex in the ChatGPT desktop app** | No | Yes, install it in ChatGPT | No |
| **Codex IDE extension** | No | Yes, synced from ChatGPT | Yes, **Settings** → **MCP servers** |

## Prerequisites

<CardGroup cols={2}>
  <Card title="OpenAI Codex" icon="https://mintcdn.com/controlplanecorporation/rFQpIcXts1y-5L7u/icons/codex.svg?fit=max&auto=format&n=rFQpIcXts1y-5L7u&q=85&s=7f6290d9a955377990c873b308593f35" width="2406" height="2406" data-path="icons/codex.svg">
    Install [Codex CLI](https://openai.com/codex)
  </Card>

  <Card title="Control Plane account" icon="user">
    Sign up at [console.cpln.io](https://console.cpln.io) if you don't have an account yet
  </Card>
</CardGroup>

<Note>
  For the latest MCP configuration options, refer to the official [OpenAI Codex documentation](https://developers.openai.com/codex).
</Note>

## Add Control Plane

<Tabs>
  <Tab title="Codex CLI" icon="terminal">
    Register the remote MCP server, then sign in.

    <Steps>
      <Step title="Register the server">
        Use the `codex mcp add` command:

        ```bash theme={null}
        codex mcp add cpln --url https://mcp.cpln.io/mcp
        ```

        <Note>
          Connecting to the bare URL uses the default **`core`** toolset profile. Append `?toolsets=mk8s` to add BYOK Kubernetes tools, or `?toolsets=full` for everything. See [toolset profiles](/ai/mcp#toolset-profiles).
        </Note>
      </Step>

      <Step title="Sign in">
        Run the login command:

        ```bash theme={null}
        codex mcp login cpln
        ```

        Your browser opens:

        1. Sign in to Control Plane (Google, GitHub, Microsoft, or SAML).
        2. Select the orgs you want this Codex install to access.
        3. Click **Authorize**.

        Your browser shows a success page. Close the tab and return to Codex.
      </Step>

      <Step title="Verify the registration">
        ```bash theme={null}
        codex mcp list
        ```

        You should see `cpln` with **enabled** status and **OAuth** auth:

        ```text theme={null}
        Name  Url                      Bearer Token Env Var  Status   Auth
        cpln  https://mcp.cpln.io/mcp  -                     enabled  OAuth
        ```
      </Step>

      <Step title="Verify live access">
        Launch Codex and ask: "list GVCs in org `<your-org>`" (using one of the orgs you authorized). You should see the GVCs in that org.
      </Step>
    </Steps>

    <Tip>
      Codex CLI can also install Control Plane from the ChatGPT Plugin directory: start Codex, run `/plugins`, switch to the directory tab, and install **Control Plane**. That route is fixed on `core`, so use `codex mcp add` above for a wider profile. Details on [ChatGPT](/ai/chatgpt).
    </Tip>
  </Tab>

  <Tab title="ChatGPT desktop app" icon="https://mintcdn.com/controlplanecorporation/xnekNgNSbgjIZIwl/icons/chatgpt.svg?fit=max&auto=format&n=xnekNgNSbgjIZIwl&q=85&s=dfbc439fa02b4758337c91d9bed1feb6" width="2406" height="2406" data-path="icons/chatgpt.svg">
    Codex running inside the ChatGPT desktop app uses ChatGPT's own plugin surface, not Codex CLI configuration. Install the Control Plane plugin once in ChatGPT and Codex picks it up there.

    <Steps>
      <Step title="Install the plugin">
        Open [the Control Plane plugin listing](https://chatgpt.com/plugins/plugin_asdk_app_6a3345aed5b081918ae752ac49e4df0e) and click **Install plugin**. If that link doesn't open the listing, click **Plugins** in the left sidebar and search for **Control Plane**.
      </Step>

      <Step title="Authorize your orgs">
        When prompted to **Connect**, sign in to Control Plane, select the orgs you want to expose, and click **Authorize**.
      </Step>

      <Step title="Use it">
        Start a new Codex session in the desktop app, then type `@` and pick **Control Plane** to invoke it explicitly.
      </Step>
    </Steps>

    <Note>
      The listing is fixed on the default **`core`** toolset profile and takes no query parameter. Full setup notes are on the [ChatGPT](/ai/chatgpt) page.
    </Note>
  </Tab>

  <Tab title="Codex IDE extension" icon="code">
    Open **Codex settings** → **Plugins**. A plugin you already installed in ChatGPT or the Codex app appears there as installed and enabled, so Control Plane needs no further setup on this surface.

    Register the MCP server directly when you want a toolset profile other than `core`.

    <Steps>
      <Step title="Add the server">
        In the extension settings, select **MCP servers** → **Add server**, then fill in:

        | Field | Value |
        | - | - |
        | **Name** | `cpln` |
        | **Type** | `Streamable HTTP` |
        | **URL** | `https://mcp.cpln.io/mcp` |

        <Note>
          Connecting to the bare URL uses the default **`core`** toolset profile. Append `?toolsets=mk8s` to add BYOK Kubernetes tools, or `?toolsets=full` for everything. See [toolset profiles](/ai/mcp#toolset-profiles).
        </Note>
      </Step>

      <Step title="Restart">
        Save the server, then select **Restart**.
      </Step>

      <Step title="Sign in">
        On first use the extension opens your browser:

        1. Sign in to Control Plane (Google, GitHub, Microsoft, or SAML).
        2. Select the orgs you want this Codex install to access.
        3. Click **Authorize**.
      </Step>

      <Step title="Verify live access">
        Ask Codex to "list GVCs in org `<your-org>`" (using one of the orgs you authorized).
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Example conversation

<Steps>
  <Step title="Set Context">
    ```text theme={null}
    Use org "my-org" and gvc "my-gvc" for context.
    ```
  </Step>

  <Step title="Deploy a Workload">
    ```text theme={null}
    Create a publicly accessible workload called "my-api" using nginx:latest on port 80.
    ```
  </Step>

  <Step title="Get the Endpoint">
    ```text theme={null}
    Monitor the readiness of my-api and give me the public endpoint once it's ready.
    ```
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Browser didn't open for sign-in">
    Some terminal setups can't launch a browser. `codex mcp login cpln` prints a fallback URL. Copy it into a browser on the same machine and complete sign-in there.
  </Accordion>

  <Accordion title="Need to change which orgs are authorized">
    On Codex CLI, re-run `codex mcp login cpln`, sign in again, and adjust your org selections on the consent screen. On the ChatGPT desktop app, click **Plugins** in the left sidebar, open **Control Plane**, disconnect it, then connect again.
  </Accordion>

  <Accordion title="Control Plane isn't listed in Codex CLI after installing it in ChatGPT">
    Run `/plugins` in Codex CLI and install **Control Plane** from the directory tab there, or register the MCP server with `codex mcp add cpln --url https://mcp.cpln.io/mcp`. Either way, start a new CLI session afterwards.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="AI Plugin" icon="puzzle-piece" href="/ai/plugin">
    Layer skills, agents, slash commands, and guardrails on top of the MCP server
  </Card>

  <Card title="ChatGPT" icon="https://mintcdn.com/controlplanecorporation/xnekNgNSbgjIZIwl/icons/chatgpt.svg?fit=max&auto=format&n=xnekNgNSbgjIZIwl&q=85&s=dfbc439fa02b4758337c91d9bed1feb6" href="/ai/chatgpt" width="2406" height="2406" data-path="icons/chatgpt.svg">
    Install the Control Plane plugin for ChatGPT on the web, desktop, and mobile
  </Card>

  <Card title="Usage Examples" icon="lightbulb" href="/ai/examples">
    Practical prompts for common Control Plane workflows
  </Card>

  <Card title="Tools Reference" icon="https://mintcdn.com/controlplanecorporation/rFQpIcXts1y-5L7u/icons/mcp.svg?fit=max&auto=format&n=rFQpIcXts1y-5L7u&q=85&s=cb54e1afd80c8345d82dc3e4c9ca2e32" href="/ai/tools" width="24" height="24" data-path="icons/mcp.svg">
    Every tool the MCP server exposes, grouped by resource
  </Card>
</CardGroup>