> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/balkanid-mcp/installation-and-setup/codex-cli.md).

# Codex CLI

Connect the [Codex CLI](https://learn.chatgpt.com/docs/extend/mcp) to BalkanID MCP.

**OAuth is preferred.** Codex can also use a Bearer API key when you need Read-only access or OAuth is unavailable.

The Codex CLI, Codex IDE extension, and ChatGPT Desktop read the **same MCP configuration**. Setting up BalkanID once makes the server available everywhere that shares that config.

### One-tap / CLI setup (OAuth — recommended)

From a terminal:

```bash
codex mcp add balkanid --url https://mcp.balkanid.app/server/mcp
codex mcp login balkanid
```

The `login` command opens your browser to complete BalkanID sign-in and consent for your tenant. Codex stores the credentials in your system keyring and refreshes them during sessions.

{% hint style="info" %}
OAuth currently requires **both Read and Write** scopes. See Authentication and Permissions.
{% endhint %}

You can also copy the MCP URL from **OAuth Connectors** in the [MCP UI](https://mcp.balkanid.app) and add it with the same `codex mcp add` command.

### Manual configuration (OAuth)

Add a Streamable HTTP server to `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):

```toml
[mcp_servers.balkanid]
url = "https://mcp.balkanid.app/server/mcp"
```

Run `codex mcp login balkanid` to authenticate.

### Manual configuration (API key fallback)

When you need a static Bearer token referenced by **name** (the token never lives in `config.toml`):

1. Create an API key in the [MCP UI](https://mcp.balkanid.app).
2. Export it, for example `export BALKANID_MCP_TOKEN=…` in the environment that launches Codex.
3. Add to `~/.codex/config.toml`:

```toml
[mcp_servers.balkanid]
url = "https://mcp.balkanid.app/server/mcp"
bearer_token_env_var = "BALKANID_MCP_TOKEN"
```

Do not commit tokens. `bearer_token_env_var` is the environment variable's name, not the secret value.

### Org-managed Codex

To share setup across a team, commit the OAuth entry (no token) to a project's `.codex/config.toml`; each developer then runs `codex mcp login balkanid` once. IT can also push configuration centrally with Codex [managed configuration](https://learn.chatgpt.com/codex/enterprise/managed-configuration). See Enterprise Rollout.

### Verify

Ask Codex: “Call whoami on BalkanID MCP.” You should see your email and tenant ID.

### Disable or remove

To pause the server without losing its setup, add `enabled = false` to its block in `config.toml`:

```toml
[mcp_servers.balkanid]
url = "https://mcp.balkanid.app/server/mcp"
enabled = false
```

To remove it and clear stored OAuth credentials:

```bash
codex mcp remove balkanid
codex mcp logout balkanid
```

Run `codex mcp list` to confirm. Changes also apply to the Codex IDE extension and ChatGPT Desktop. See Troubleshooting if Codex stops connecting.

### Official documentation

OpenAI documentation for MCP in Codex:

* [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp) — Codex Docs
* [Config Reference](https://learn.chatgpt.com/codex/config-file/config-reference) — Codex Docs


---

# 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.balkan.id/balkanid-mcp/installation-and-setup/codex-cli.md?ask=<question>&goal=<user_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.