Codex + Squall MCP

Connect Codex to Squall Studio

Squall Studio has a Streamable HTTP MCP server. Add it to Codex once and Codex can read your projects, inspect episodes, patch shots and locations, and start media generation jobs while you work from the CLI, ChatGPT desktop app, or IDE extension.

This uses your Squall Studio account only. The API key controls what Codex can do, and every MCP call still goes through Squall's ownership, billing, and permission checks.

Codex clients

CLI, desktop, IDE

Auth

Env bearer token

Tools

25 available

Before you start

You'll need:

A Squall Studio account with at least one project.
Codex CLI, the ChatGPT desktop app, or the Codex IDE extension.
A signed-in Codex client. In the CLI, run codex and complete the sign-in flow if prompted.
Credits in your Squall account if you want Codex to generate media. Check your balance.

Step 1 - Create an API key

Go to squallstudio.com/api-keys, name the key something clear like Codex on my laptop, and pick its permissions.

Permission	What Codex can do
Read only	Read your projects, scripts, shots, characters, locations, and job history. Cannot change anything.
Read + edit scripts	Also lets Codex rewrite dialogue, shot details, and locations. Edits overwrite in place and cannot be undone. Does not spend credits.
Read + generate media	Also lets Codex start image, video, and music generation. These calls spend real credits.

Start with Read only. Create a second key with editing or generation access when you are ready for Codex to change project data or spend credits.

Press Create key and copy the token. It starts with sw_live_ and is shown exactly once. If you lose it, revoke the key and create a new one.

Treat the key like a password

Anyone holding it can read your projects and, if it has generation permission, spend your credits. It cannot sign in to the web app, change your account, or create more keys.

Step 2 - Save the token

Keep the Squall key in an environment variable and point Codex at that variable. This keeps the token out of ~/.codex/config.toml.

bash

export SQUALL_STUDIO_API_KEY="sw_live_your_key_here"

Put the same export in your shell profile if you want future terminal sessions to inherit it. This is the cleanest path for Codex CLI. If you use the ChatGPT desktop app or IDE extension from a GUI launcher, it may not inherit shell variables; use the MCP server UI's bearer-token field or launch the client from an environment that contains SQUALL_STUDIO_API_KEY.

Step 3 - Connect Codex

Codex CLI

Add Squall Studio as a Streamable HTTP MCP server:

bash

codex mcp add squall-studio \
  --url https://squallstudio.com/api/mcp \
  --bearer-token-env-var SQUALL_STUDIO_API_KEY

Then check that Codex saved the server:

bash

codex mcp list

Start Codex from the same environment and inspect active MCP servers:

bash

codex
/mcp

ChatGPT desktop app and Codex IDE extension

These clients share the same Codex MCP server configuration. If you added the server with the CLI and used bearer_token_env_var, confirm the app process can see SQUALL_STUDIO_API_KEY; GUI-launched apps often do not inherit terminal exports.

To configure from the UI, open MCP servers, select Add server, choose Streamable HTTP, name it squall-studio, set the URL to https://squallstudio.com/api/mcp, and use the Squall API key as the bearer token. Save, then restart the client.

Manual config.toml

For fine-grained control, add this to ~/.codex/config.toml or to a trusted project-scoped .codex/config.toml:

toml

[mcp_servers.squall-studio]
url = "https://squallstudio.com/api/mcp"
bearer_token_env_var = "SQUALL_STUDIO_API_KEY"
default_tools_approval_mode = "writes"

Recommended approval mode

writes lets Codex use read tools without extra ceremony while asking before tools that are not marked read-only. Use prompt if you want a checkpoint before every Squall MCP tool call.

Step 4 - Try it

In Codex, ask for the outcome you want. You do not need to call Squall tools by name; Codex can inspect the tool catalog and choose the right call.

Getting oriented

Use Squall Studio to list my projects.

Open Ashes of Identity and summarize the latest episode structure.

Read the episode editor payload for episode 1 and tell me which shots still need media.

Safe review

Read shot 4, show me the current dialogue and blocking, and propose a patch before changing anything.

List locations used in episode 1 and tell me which scenes each one affects.

Find failed generation jobs in this project and group them by failure reason.

Editing

Needs a Read + edit scripts key.

After I approve, tighten Elena's second line in shot 4 without changing camera movement.

Patch the ballroom location description to feel more old-money, then show every scene that now uses the revised location.

Update only the short shot dialogue fields that contain typos and summarize the exact changes.

Generating

Needs a Read + generate media key.

Tell me how many character reference images are missing, ask for approval, then generate them.

Generate a background plate for short shot 1 of shot 3 and return the job id.

Check whether episode 1 is assembled, then generate episode music if it is ready.

How approvals work

Codex has its own approval controls, and Squall has API-key scopes. They work together.

Codex approval mode controls the prompt. It decides when Codex asks you before using an MCP tool.
Squall scopes control server permission. A read-only Squall key cannot edit or generate, even if Codex approval mode allows the call.
Use the app as your source of truth. Edits and generation jobs appear in the same project UI and billing history as normal web-app actions.

How generation works

Generation is asynchronous. Codex receives a job id immediately, then can poll the job until it succeeds or fails.

Codex calls a generate_* tool and receives { jobId, status: "queued" }.
Credits are reserved when the job starts.
Codex uses get_job to check progress.
The finished asset appears in Squall Studio's project library.

Retries never double-charge

Generation tools use idempotency keys. Retrying an interrupted call with the same key returns the original job instead of starting and billing a duplicate.

What Codex can and can't do

It can read

Projects and episodes, scripts, scenes and shots, characters and looks, locations, generated assets, and job history.

It can edit

Shots and locations with a script:write key. Ask Codex to show the current fields and proposed patch before it writes.

It can generate

Shot clips, character images, location images, shot background plates, and episode music with a generation:write key.

It can't replace the app

Creating projects, approving scripts, restructuring episodes, billing changes, and API-key management stay in the Squall Studio web app.

Tool reference

Useful when you want to constrain Codex or debug an MCP call.

Read tools

Read the production state an agent needs before planning edits or generation.

projects:read

Tool	Returns
`list_projects`	Project summaries.
`get_project`	Project summary.
`get_project_episodes`	Episode records.
`get_episode`	Episode record.
`get_episode_editor`	Episode editor payload. Prefer this before multi-step episode review because it reduces lookup drift.
`get_episode_shots`	Shot records.
`list_episode_segments`	Episode segment records.
`get_scene_assets`	Scene asset payload.
`get_project_script`	Project script payload.
`get_project_characters`	Character records.
`get_character`	Character record.
`get_character_looks`	Character look records.
`get_project_locations`	Location records.
`get_location`	Location record.
`get_asset_library`	Asset library payload.
`get_job`	Generation job status and output. Use this to poll jobs returned by generation tools.
`list_project_jobs`	Generation job records.

Edit tools

Patch authored production data after reading it first.

script:write

Tool	Does
`update_shot`	Overwrite selected fields on one shot. Send only changed fields. Dialogue edits go through camera_setup.short_shots[].dialogue_covered. Writes immediately and cannot be undone.
`update_location`	Overwrite selected fields on one location. Locations are shared across scenes. Text/image-affecting edits mark the existing location image stale; mood and episode assignment edits do not.

Generation tools

Start billed async generation jobs and poll them with get_job.

generation:write

Tool	Starts
`generate_script`	Write a full multi-episode script from a premise, as a new project. Creates a new project rather than acting on an existing one. The longest job in the system — poll get_job for phase and completedEpisodes.
`generate_shot_clip`	Generate a video clip for a single episode shot. Idempotency keys prevent duplicate billed jobs on retries.
`generate_character_image`	Generate a reference image for a character.
`generate_location_image`	Generate a reference image for a location.
`generate_shot_background_image`	Generate an empty background plate for one short shot.
`generate_episode_music`	Generate a background music track for an episode. Requires the episode to already have an assembled video.

Credits and billing

Generation through Codex costs exactly what the same generation costs in the web app. It uses the same Squall credit balance and the same job history.

Read and edit tools do not spend credits. Image, video, and music generation tools do spend credits when the job starts.

Ask for a count first

Before broad requests like generating every missing character image, ask Codex to count the jobs and wait for approval before it starts them.

Troubleshooting

codex: command not found

Install Codex first, then open a new terminal and run codex again.

squall-studio is not listed by codex mcp list

Re-run codex mcp add with the --url flag, or check ~/.codex/config.toml for a [mcp_servers.squall-studio] block.

[403] This endpoint requires an API key.

The SQUALL_STUDIO_API_KEY variable is missing from the process running Codex, or the key was revoked. Export it in the same terminal before starting Codex, then reconnect or restart the client.

[403] This API key does not have the required scope: generation:write

The key can read but cannot spend credits. Create a new Squall key with Read + generate media and reconnect Codex with that key.

[403] This API key does not have the required scope: script:write

The key can read but cannot edit. Create a new Squall key with Read + edit scripts and reconnect Codex with that key.

Codex asks before tool calls

That is expected when approval settings require confirmation. Use default_tools_approval_mode = "writes" if you want read tools to run smoothly while write and generation tools still ask.

ChatGPT web does not show my local MCP server

ChatGPT web does not read local Codex config. Use Codex CLI, the ChatGPT desktop app, or the IDE extension for this local MCP setup.

Reconnect from scratch

If the server entry is stale, remove it and add it again:

bash

codex mcp remove squall-studio
codex mcp add squall-studio \
  --url https://squallstudio.com/api/mcp \
  --bearer-token-env-var SQUALL_STUDIO_API_KEY

Technical details

Endpoint	`https://squallstudio.com/api/mcp`
Transport	Streamable HTTP (MCP)
Auth	`Authorization: Bearer sw_live_...`
Scopes	projects:read, script:write, generation:write
Tools	25 total

Codex supports Streamable HTTP MCP servers with bearer-token authentication. Squall Studio uses that path, with your Squall API key supplied as the bearer token.

Codex config	`~/.codex/config.toml` or trusted `.codex/config.toml`
CLI add	`codex mcp add squall-studio --url ...`
Verify	`codex mcp list` or `/mcp` in the Codex TUI
OpenAI docs	Codex MCP documentation

Create an API key Back to MCP guide