> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI

> Connect HeyGen to OpenAI Codex CLI via MCP. Generate AI avatar videos, translate clips, and run lipsync from your terminal with natural-language prompts.

Connect HeyGen's Video Agent to OpenAI Codex CLI to generate AI avatar videos from your terminal. Once configured, Codex can script, render, and deliver videos through natural-language prompts without leaving your development workflow.

<Note>
  For the ChatGPT app, see [OpenAI](/mcp/open-ai) instead. This page covers the `codex` command-line tool.
</Note>

## Prerequisites

* Codex CLI installed ([installation guide](https://developers.openai.com/codex/cli))
* A HeyGen account with Video Agent access

## Adding the MCP Server

Run the following command in your terminal (not inside the Codex CLI):

```text theme={null}
codex mcp add heygen --url https://mcp.heygen.com/mcp/v1
```

Two details matter here:

* **`--url` is required.** Without it, Codex treats the address as a command to launch a local process rather than a remote HTTP server.
* **Omit the trailing slash.** Codex builds the OAuth discovery path from the URL you supply, and a trailing slash produces a path that redirects rather than resolving directly.

Codex detects HeyGen's OAuth support and starts the browser flow automatically:

```text theme={null}
Added global MCP server 'heygen'.
Detected OAuth support. Starting OAuth flow…
Successfully logged in.
```

### Alternative: Direct Config Edit

You can also add the server by editing `~/.codex/config.toml` directly:

```toml theme={null}
[mcp_servers.heygen]
url = "https://mcp.heygen.com/mcp/v1"
```

The key must be `url`. A `command` key registers the server as a local process and OAuth will not run. After editing, authenticate with:

```text theme={null}
codex mcp login heygen
```

## Authentication

HeyGen uses browser-based OAuth, so no API key is needed. Codex opens the authorization page on first setup. If you skipped it or your session expired, run `codex mcp login heygen` and complete the flow in your browser. Tokens are stored encrypted under `~/.codex/`.

To sign out:

```text theme={null}
codex mcp logout heygen
```

## Verifying the Connection

```text theme={null}
codex mcp list
```

You should see `heygen` with `Auth: OAuth`:

```text theme={null}
Name    Url                            Bearer Token Env Var  Status   Auth
heygen  https://mcp.heygen.com/mcp/v1  -                     enabled  OAuth
```

For transport details, run `codex mcp get heygen`. A correctly configured server reports `transport: streamable_http`.

## Usage

Once connected, prompt Codex with a video generation request:

```text theme={null}
Generate a 60-second explainer video about our new API endpoints using HeyGen.
```

Codex calls HeyGen's Video Agent to handle scripting, avatar selection, and rendering. Tools are exposed with an `mcp__heygen__` prefix, covering video generation, avatar and voice creation, translation, lipsync, and asset management. Completed videos are accessible from the **Projects** page in your HeyGen dashboard.

### Loading HeyGen Skills (Recommended)

For better prompt structure and higher-quality output, instruct Codex to read HeyGen's prompt engineering guidelines before generating:

```text theme={null}
Before writing any video prompts, read the HeyGen skills at:
https://github.com/heygen-com/skills

Follow SKILL.md, references/prompt-optimizer.md, and references/video-agent.md
to structure each prompt with scenes, timing, visual style, and copy rules.
```

Codex also supports installable skills. See [Install Skills](/skills/install) for the `~/.codex/skills/` setup.

## Configuration Scoping

Codex stores MCP servers globally. There is no project-scoped equivalent, so `heygen` is available in every directory once added.

| Scope                | File Location          | Availability |
| -------------------- | ---------------------- | ------------ |
| Global (only option) | `~/.codex/config.toml` | All projects |

## Troubleshooting

<Warning>
  **`Error: No authorization support detected`**

  Your configured URL has a trailing slash. Re-add it without one:

  ```text theme={null}
  codex mcp remove heygen
  codex mcp add heygen --url https://mcp.heygen.com/mcp/v1
  ```
</Warning>

<Warning>
  **`Error: OAuth login is only supported for streamable HTTP servers`**

  The server was added without `--url`, so Codex registered the address as a launch command. Check `~/.codex/config.toml`: the entry must use `url = "..."`, not `command = "..."`. Remove and re-add with `--url`.
</Warning>

If tools do not appear after a successful login, restart Codex CLI so it reconnects to the server.