Skip to main content
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.
For the ChatGPT app, see OpenAI instead. This page covers the codex command-line tool.

​
Prerequisites

​
Adding the MCP Server

Run the following command in your terminal (not inside the Codex CLI):
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:

​
Alternative: Direct Config Edit

You can also add the server by editing ~/.codex/config.toml directly:
The key must be url. A command key registers the server as a local process and OAuth will not run. After editing, authenticate with:

​
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:

​
Verifying the Connection

You should see heygen with Auth: 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:
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. For better prompt structure and higher-quality output, instruct Codex to read HeyGen’s prompt engineering guidelines before generating:
Codex also supports installable skills. See Install Skills 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.

​
Troubleshooting

Error: No authorization support detectedYour configured URL has a trailing slash. Re-add it without one:
Error: OAuth login is only supported for streamable HTTP serversThe 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.
If tools do not appear after a successful login, restart Codex CLI so it reconnects to the server.