# Use BuildBase in Codex

Add BuildBase's MCP server to Codex in config.toml, sign in with codex mcp login, and manage your organization from the Codex CLI or IDE extension.

This page is part of **BuildBase in your AI tools**: it connects Codex to BuildBase's own MCP server so you can manage your BuildBase organization while you code. Codex signs in as you and never sees your organization's secrets.

> **Note:**
  Want your own app to be agent-ready? See [Let your users connect Codex to your
  app](/agents/clients/codex), in **Agent-ready apps**.

## What you need

- Codex: the CLI, the IDE extension or the ChatGPT desktop app.
- A BuildBase console account, whichever way you sign in to the console.
- An organization whose **AI agents** setting is not **Off** ([choose what agents may do](/console/ai-agents#choose-what-agents-may-do)). Agents can read by default.

## Add the server

Add an entry to `~/.codex/config.toml`:

```toml
[mcp_servers.buildbase-console]
url = "https://api.console.buildbase.app/mcp"
```

The CLI, the IDE extension and the ChatGPT desktop app share this file, so one entry serves all three.

## Sign in

A remote server signs in with OAuth by default in Codex.

1. Run:

   ```bash
   codex mcp login buildbase-console
   ```

   On a machine with no browser, add `--no-browser` and open the link it prints elsewhere.

2. Sign in on BuildBase's sign-in page with your console account and your usual second step.
3. Read the consent screen: it names the client and the scopes it asks for, `console:read` and `console:write` to start. Approve it.

When a task needs more, such as an export or a delete, Codex is told which scope is missing ([what an agent asks for](/console/ai-agents#what-an-agent-asks-for-at-sign-in)).

## What you see when you connect

Once you have signed in, BuildBase shows the consent screen in your browser. It names the tool, lists the scopes it asks for and the server the access is for, and changes nothing until you choose **Allow access**. Here it is for a tool that registered itself:

![BuildBase's consent screen for a tool that registered itself, here Example Agent: a warning that the app gave itself its name and nobody has checked it, what it may do as you, console:read and offline_access, the access to use at https://api.console.buildbase.app/mcp, and Allow access and Deny ringed](/images/console/ai-agents/hosted-consent.webp)

## Use it while you code

Ask, for example:

- "Which environment variables does this app need for Acme? Fill `.env.example`, secrets left blank."
- "Export Acme's blueprint and tell me which email templates it has."
- "Search the BuildBase docs for workspaces and add a workspace switcher here."

More, with what each one asks you to approve: [example prompts](/console/ai-agents#example-prompts).

## Without a person: an API key

For a job with nobody to sign in, name an environment variable that holds one of your organization's API keys:

```toml
[mcp_servers.buildbase-console]
url = "https://api.console.buildbase.app/mcp"
bearer_token_env_var = "BUILDBASE_API_KEY"
```

The key works in its own organization only, the **AI agents** setting still applies, and changes are recorded as the key's ([connect with an API key](/console/ai-agents#connect-with-an-api-key)).

## What differs in Codex

- **One file for three apps**, so a change to the entry reaches the CLI, the IDE extension and the ChatGPT desktop app together.
- **Timeouts.** Codex waits 10 seconds for a server to start (`startup_timeout_sec`) and 60 seconds for a tool (`tool_timeout_sec`). A large blueprint plan or export can take longer: raise `tool_timeout_sec` in the entry.
- **Approvals of a change.** Where Codex can ask you a question itself, the change BuildBase wants to make is shown to you and nothing happens unless you approve it. Otherwise it states the change and confirms it with a one-time code ([what stays with you](/console/ai-agents#what-stays-with-you)).

## If something goes wrong

| What you see                                       | Why                                                                     | What to do                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Tools fail with an authorization error             | You have not signed in, or the session ended                            | Run `codex mcp login buildbase-console`                                        |
| A blueprint plan or export times out               | It took longer than `tool_timeout_sec`                                  | Raise `tool_timeout_sec` in the entry                                          |
| Codex says the organization does not let agents in | Its **AI agents** setting is **Off**, or your agent is blocked there    | An owner or admin changes it under **Security**, **AI agents**                 |
| Every change is refused                            | The organization is **Read only**, or you did not grant `console:write` | An owner or admin sets **Read and change**; approve `console:write` when asked |

To disconnect, remove the entry from `config.toml` and [disconnect the agent](/console/ai-agents#disconnect-an-agent) in BuildBase, which ends its session at once.

## Related

- [BuildBase in your AI tools](/console/ai-agents): the server, its tools, and what stays with you.
- [Use BuildBase in Claude Code](/console/ai-agents/claude-code) and [Use BuildBase in ChatGPT](/console/ai-agents/chatgpt).
- [Let your users connect Codex to your app](/agents/clients/codex): the same client in **Agent-ready apps**.
- OpenAI's own guide: [MCP in Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

## Frequently asked questions

### Where does Codex keep the server?

In ~/.codex/config.toml. The Codex CLI, the Codex IDE extension and the ChatGPT desktop app read the same file, so you add BuildBase once.

### How do I sign in on a machine with no browser?

Run codex mcp login buildbase-console --no-browser and open the link it prints on another device.

### Can Codex use an API key instead of signing in?

Yes. Put the key in an environment variable and name it with bearer_token_env_var in the server's entry. The organization's AI agents setting still applies.