# How to build a generative media integration with Codex > Connect Codex to Runway Dev MCP and let it build, debug and maintain a video, image or audio generation integration. Author: Runway · Published: 2026-09-17 · Updated: 2026-09-17 · Source: https://dev.runwayml.com/learn/build-with-codex Codex can build, debug and maintain a video, image, audio or real-time avatar generation API integration autonomously, end to end. Connecting it to [Runway Dev MCP](https://docs.dev.runwayml.com/guides/mcp/) is what makes that possible: the agent works from your Runway Dev account and the live model catalog rather than from documentation alone, so it picks models against current prices and input limits, configures whatever the integration needs, and reads back the actual cause when a generation fails. This walks through the setup and the first build, from the login command to a working feature in your app. ## Step 1: Add Runway Dev MCP to Codex | | Codex app | Terminal | | ---------------- | --------------------------------- | --------------------------------------------------------------------------------- | | **Connect** | Quickstart, then Open in Codex | `codex mcp add runway-dev-mcp --url https://dev.runwayml.com/mcp` | | **Authenticate** | Approve in the browser when asked | `codex mcp login runway-dev-mcp --scopes openid,profile,email,mcp:read,mcp:write` | | **Config file** | Not applicable | `~/.codex/config.toml`, as an alternative to the add command | | **Skills** | Installed for you | `npx skills add … --agent codex` | ### If you’re using the Codex app: start from Quickstart Open Quickstart in [Runway Dev](https://dev.runwayml.com/) and click **Open in Codex**. It opens a new thread carrying a prompt that points at Runway Dev's setup brief, and the agent works from there: it inspects your project, reads the documentation, installs the Runway Dev skills where they are supported, and connects the Runway Dev MCP. Approve the sign-in in your browser when it asks. That button is an app deep link, so it only works if you have the Codex app. From the terminal, use the route below. ### If you’re using Codex from the terminal: add the server yourself ```bash codex mcp add runway-dev-mcp --url https://dev.runwayml.com/mcp codex mcp login runway-dev-mcp --scopes openid,profile,email,mcp:read,mcp:write ``` **Request the scopes explicitly, as above.** Codex has a [known scope-discovery issue](https://github.com/openai/codex/issues/15643), so leaving it to discover them can leave you connected but without the access the tools need. You can also declare the server in `~/.codex/config.toml` instead of using `codex mcp add`, as the [Runway Dev MCP setup guide](https://docs.dev.runwayml.com/guides/mcp/) describes: ```toml [mcp_servers.runway-dev-mcp] url = "https://dev.runwayml.com/mcp" ``` Then run the same login command to complete the browser sign-in. **If Codex connects but reports a missing `mcp:read` scope,** the cached authorization is the problem. Replace it: ```bash codex mcp logout runway-dev-mcp codex mcp login runway-dev-mcp --scopes openid,profile,email,mcp:read,mcp:write ``` Complete the sign-in yourself rather than asking Codex to automate it. No API key goes into `config.toml` or anywhere else: the connection is OAuth, and your keys stay in your Runway Dev account. **Confirm it worked.** Ask who you are and how many credits you have. It should return the email on your Runway Dev account and your current balance. ### If you’re using ChatGPT rather than Codex Runway Dev MCP can also be added to ChatGPT as a custom connector, pointed at the same URL, `https://dev.runwayml.com/mcp`. That is useful for asking about your account, your models and your tasks in conversation. It is not the route for building, since Codex is the surface that works inside your codebase. Use Codex for the integration and ChatGPT for the questions. ## Step 2: Install the Runway Dev skills (optional) **Skip this if you started from Quickstart.** The agent installs them for you. Otherwise, Runway publishes agent skills that teach Codex how each surface works before it writes anything: ```bash npx skills add runwayml/skills --skill runway-dev --skill runway-dev-models --agent codex -y ``` Swap the surface skill for the one that matches the job: `runway-dev-models`, `runway-dev-model-routers`, `runway-dev-characters` or `runway-dev-recipes`. The shared `runway-dev` skill comes along either way. Skipping it altogether is fine too. Codex then works from the documentation, which it can read as raw Markdown by appending `.md` to any docs path. ## Step 3: Add your API key to the project The MCP connection is OAuth, but a live generation call still needs a key of its own. The first time Codex is ready to run something, it asks for `RUNWAYML_API_SECRET` in the project environment. Create the key in your [Runway Dev](https://dev.runwayml.com/) account and add it to the project's environment file yourself. Do not paste it into the thread, and do not let it end up hardcoded: Codex reads it from the environment. ## Step 4: Describe what you are building Codex now has your codebase, your account and the live catalog, so it does not need to be told which endpoint to call. It needs to know what you are building. - Say what someone using your product should be able to do. - Name what you already have as input: a product photo for image to video, a script for text to video, a catalog feed. - Name what you need out: duration, resolution, format, whether it needs audio. - Say where it runs: a route in your web app, a background job, a nightly batch. - Give your constraints: a ceiling per generation, how long a user will wait, the quality bar you are holding. - Ask it to explain which Runway Dev surface it plans to use, and why, before it writes any code. Runway Dev offers more than a generation endpoint, and the right surface depends on the job: - **A Model Router**, when you want the best model for each request without evaluating models yourself. Your code passes a config ID instead of a model name, and Codex can create the router and rewrite the calling code in the same turn. - **A Recipe**, when Runway has already built and tuned the use case. One call returns a production-ready asset, with the model selection, prompting and chaining already done. - **A custom Workflow**, when the pipeline is specific to you and takes several steps. It is built visually in the Runway Creative App, then published as an endpoint your integration calls once. - **A model called directly**, when you already know which one you want. When a generation fails, Codex looks the task up itself and reads the actual cause, whether that is a moderation rejection, an asset over a size limit or a malformed request body, rather than working backwards from a status code. You are now ready to let Codex handle media generation with Runway Dev autonomously, end to end. Connect Runway Dev MCP from Quickstart and describe your first feature. [Create an account](https://dev.runwayml.com/login?returnTo=%2F&screen_hint=signup) to start building. ## FAQ **How do I connect Codex to Runway Dev?** Run `codex mcp add runway-dev-mcp --url https://dev.runwayml.com/mcp`, then `codex mcp login runway-dev-mcp --scopes openid,profile,email,mcp:read,mcp:write`. Request the scopes explicitly, because Codex has a known scope-discovery issue. **Why does Codex need explicit scopes for Runway Dev MCP?** Codex has a [known scope-discovery issue](https://github.com/openai/codex/issues/15643), so it can connect without requesting the scopes its tools need. Passing `openid,profile,email,mcp:read,mcp:write` at login avoids a connection that looks fine but cannot read anything. **Why does Codex report a missing `mcp:read` scope?** The cached authorization is missing the scope. Run `codex mcp logout runway-dev-mcp`, then log in again with `codex mcp login runway-dev-mcp --scopes openid,profile,email,mcp:read,mcp:write` to replace it. **Can I add Runway Dev MCP to `config.toml` instead of using the CLI?** Yes. Add an `[mcp_servers.runway-dev-mcp]` block in `~/.codex/config.toml` with `url = "https://dev.runwayml.com/mcp"`, then run the login command to complete the browser sign-in. **How do I connect Runway Dev to the Codex app?** Open Quickstart in Runway Dev and click Open in Codex. It opens a new thread with a prompt pointing at Runway Dev's setup brief, and the agent handles the setup from there, including connecting the MCP. **Does the Open in Codex button work from the terminal?** No. The Quickstart buttons are app deep links, so they hand off to the Codex app. From the terminal, use Copy prompt in Quickstart and paste the prompt into Codex instead. **Can I use Runway Dev MCP with ChatGPT?** Yes, as a custom connector pointed at `https://dev.runwayml.com/mcp`. That works for asking about your account, your models and your tasks. For building an integration, use Codex, since it is the surface that works inside your codebase. **Do I put my Runway API key in the Codex MCP config?** No. The connection uses OAuth in the browser, so no key belongs in `config.toml` or any other MCP config. Keys stay in your Runway Dev account, where you can rotate them. **Do I still need a Runway API key with Codex?** Yes, for live generation calls from your app. Codex asks for `RUNWAYML_API_SECRET` in the project environment the first time it is ready to run something. Add it yourself rather than pasting it into the thread. **How do I know Codex is connected to Runway Dev?** Ask who you are and how many credits you have. It returns the email on your Runway Dev account and your current credit balance. **Are there Runway Dev skills for Codex?** Yes. Install them with `npx skills add runwayml/skills --skill runway-dev --skill --agent codex -y`. The surface skills cover models, model routers, characters and recipes. **Can Codex create a Model Router for me?** Yes. Ask for a router with the settings you want and for the integration to be updated to use it. It creates the configuration, reads it back, and rewrites the calling code to pass the config ID. **Can Codex spend my credits without asking?** No. Runway Dev's setup brief tells the agent to treat a billable test call as optional unless you asked for one, and to ask before creating or changing anything live in the account. **How does Codex debug a failed generation?** It looks the task up through the MCP and reads the recorded cause, such as a moderation rejection, an asset over a size limit or a malformed request body, instead of guessing from the error string. **What can I build with Codex and Runway Dev?** Video, image and audio generation, real-time conversational video agents through Characters, upscaling and HDR output, using models from Runway and from other frontier labs.