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

# Connect Codex

> Add Agent Vault to OpenAI Codex with one command that also starts sign-in, in about 2 minutes.

Connect OpenAI's Codex CLI to Agent Vault so it can check out and sign in for
you, using only mock tokens. It takes about 2 minutes: one command adds the
server and starts the sign-in.

<Frame caption="Copy the line for Codex from your dashboard, then add the server and sign in.">
  <video controls muted playsInline preload="metadata" className="w-full" poster="/images/agents/codex-poster.webp" src="https://mintcdn.com/self-labs/VeDWRFlNWGO5jQN6/videos/agents/codex.mp4?fit=max&auto=format&n=VeDWRFlNWGO5jQN6&q=85&s=c8ebbfbb97fa48925658652c42d18983" aria-label="A terminal running codex mcp add, which starts sign-in, next to the dashboard's Connect another agent panel with Codex picked." data-path="videos/agents/codex.mp4" />
</Frame>

## Before you start

* An Agent Vault account, with a card if your agent will check out. New here?
  The [Quickstart](/get-started/quickstart) sets one up in about 5 minutes.
* The Codex CLI, installed and signed in.

## Connect Codex

<Tabs>
  <Tab title="Paste one line (recommended)">
    <Steps>
      <Step title="Paste this into Codex">
        ```text theme={null}
        Read https://mcp.agentvault.io/skill.md and follow it to connect Agent Vault.
        ```

        Codex reads the connect skill and adds the server. If your browser is on the
        same machine, that also starts the sign-in.
      </Step>

      <Step title="Sign in">
        Open the sign-in link Codex gives you and sign in on the Agent Vault sign-in
        page, with your Agent Vault account.
      </Step>

      <Step title="Start a new session">
        Codex keeps the MCP servers it started with, so the session you pasted into
        won't see Agent Vault. Start a new Codex session for the next steps.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Set it up by hand">
    <Steps>
      <Step title="Add the server">
        ```bash theme={null}
        codex mcp add agent-vault --url https://mcp.agentvault.io/mcp
        ```

        Codex answers `Added global MCP server 'agent-vault'`, then
        `Detected OAuth support. Starting OAuth flow…`. Keep it running, open the link
        it prints and sign in on the Agent Vault sign-in page.
      </Step>

      <Step title="Or, on a server, add it to the config file">
        If Codex runs on a different machine from your browser, skip the command above:
        its sign-in would wait for a callback that can't reach it. Add this to
        `~/.codex/config.toml` instead, keeping everything already in the file. It
        starts nothing.

        ```toml ~/.codex/config.toml theme={null}
        [mcp_servers.agent-vault]
        url = "https://mcp.agentvault.io/mcp"
        ```

        Then sign in:

        ```bash theme={null}
        codex mcp login agent-vault --no-browser
        ```

        Open the link it prints and sign in. Your browser then fails to load an address
        starting with `http://127.0.0.1`. Paste the whole address into the waiting
        `codex mcp login` within a few minutes.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Choose what it may use

A new connection starts with nothing granted, so your agent can't use a card or
a login yet. Until you choose, its first tool call answers:

```text theme={null}
Choose what this app may use in Agent Vault before it can act: open the connection's page in the dashboard.
```

The connection itself appears in the dashboard only once your agent makes its
first tool call, so make that call first.

<Steps>
  <Step title="Make a first call">
    Ask your agent to call `get_token_catalog`. It answers with the message above,
    and the call creates the connection.
  </Step>

  <Step title="Open Connected apps">
    In the dashboard sidebar, under **Vault**, click **Connected apps**. The new
    connection's row shows **Choose what it may use**.
  </Step>

  <Step title="Pick its cards and logins">
    Click **Choose access**. Under **Cards** and **Logins**, pick **All**, or keep
    **Only selected** and tick the ones this agent may use.
  </Step>

  <Step title="Check the choices, then click Save access">
    Your first connection's dialog opens with nothing ticked. After that, a new
    connection's dialog opens with the choices of the connection you used most
    recently, so saving it unchanged grants the same cards and logins, and the same
    three switches: **Let this app create and change its own logins**, **Ask me
    before every purchase from this app** and **Fill a test card instead of my
    card**. Check all of them for this agent before you click **Save access**.
  </Step>
</Steps>

You can change or revoke the connection on the same page at any time. See
[Connected apps](/dashboard/api-keys#connected-apps).

## Check it works

In a new Codex session, ask Codex to call the Agent Vault tool
`get_token_catalog`. It answers with the mock tokens for the cards and logins
you allowed, such as `av_card_1_number_u7x2k`. Your real card number never
reaches Codex.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Codex doesn't see the Agent Vault tools">
    A running session keeps the MCP servers it started with. Start a new session
    and ask again.
  </Accordion>

  <Accordion title="codex mcp add waits and never finishes">
    It is waiting for the sign-in callback, which can't reach a remote machine. Stop
    it, add the server to `~/.codex/config.toml` and sign in with
    `codex mcp login agent-vault --no-browser`.
  </Accordion>

  <Accordion title="The first tool call says to choose what this app may use">
    The connection has nothing granted yet. Follow
    [Choose what it may use](#choose-what-it-may-use), then ask again.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Your first checkout" icon="cart-shopping" href="/guides/first-checkout">
    Have Codex buy something, start to finish.
  </Card>

  <Card title="Tool reference" icon="wrench" href="/mcp/tool-reference">
    Every tool your agent now has.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.