How to use isayaction from Codex or Claude Code via MCP: script to storyboard to first frames

From a script to a storyboard with an AI Agent

isayaction is an AI storyboard MCP server and AI short drama workspace. Codex or Claude Code can operate your projects and canvas through MCP: organize a script into episodes, write shots, create character references and submit first-frame image tasks. This tutorial covers a script to storyboard agent workflow; model output and character consistency depend on your chosen model and references.

The dialogue below is an illustrative request, not a recorded production run or a guarantee of output quality. Keep the first attempt small: one episode and three shots, then review the canvas before expanding.

1. Create a scoped key

Open MCP setup at /mcp and sign in to create a key. Manage scopes, revoke access and set a cumulative spending limit at /access-keys. The key uses its owner's personal resources; it cannot manage payments, administration or other users' projects.

New MCP keys use the default common-tool profile and eight core scopes. Legacy keys and API requests that omit mcpToolProfile remain expert. Tools are always filtered by scopes. For characters, existing shot edits, finished video or the hosted Agent, use ?profile=expert in the server URL, enable the required scopes and reconnect; the profile never grants permissions.

Paid model and media calls execute and deduct credits directly, without per-call approval. The key holder is responsible for the charges and consequences. Delegating to the built-in Agent also charges text and media usage; external client fees are separate. Local rendering and transcription currently do not charge model credits. Check your balance and pricing before running generation.

Store your key locally in ISAYACTION_API_KEY. In a Unix shell, use export ISAYACTION_API_KEY='<YOUR_KEY>'; in PowerShell, use $env:ISAYACTION_API_KEY='<YOUR_KEY>'. Replace the placeholder privately with your yc_live_ key. Do not paste a real key into a prompt, shared script or screenshot.

How to set a key spending limit

The platform sets no default spending cap: new keys are unlimited. MCP/API calls deduct credits directly. Agent loops, mistakes or a leaked key can cause ongoing charges. We recommend setting a cumulative limit such as 200, 500 or 1000 credits; you decide whether to set one.

On /access-keys, choose a preset or enter a custom amount in the spending-limit block before creating a key. Leave it blank or select Unlimited for no cap. When getting a key from Home or /mcp, use the same block in the one-time key dialog and click Save spending limit; until saved, the new key is unlimited. You may also set it later on /access-keys using Edit limit, then save.

Each key shows Used / Limit and a warning at 80% usage. You can change the cap anytime. The cap is cumulative, not monthly; refunds and key rotation do not reset usage. A limit of 0 blocks new paid calls. The limit does not revoke the key or cancel tasks already submitted.

2. Connect Codex or Claude Code

The remote endpoint is https://isayaction.com/api/mcp. It uses Streamable HTTP with Authorization: Bearer yc_live_...; it does not authenticate with a browser Cookie. Run the matching command after setting the environment variable:

Codex command: codex mcp add isayaction --url https://isayaction.com/api/mcp --bearer-token-env-var ISAYACTION_API_KEY

For unattended `codex exec` runs, add `default_tools_approval_mode = "approve"` to the `[mcp_servers.isayaction]` section of `~/.codex/config.toml`. You can use `default_tools_approval_mode = "writes"` instead to auto-approve read-only tools and require confirmation for writes or paid calls.

Claude Code command (Unix shell): claude mcp add --transport http isayaction https://isayaction.com/api/mcp --header "Authorization: Bearer $ISAYACTION_API_KEY"

For Claude Code in PowerShell, replace $ISAYACTION_API_KEY in the header with $env:ISAYACTION_API_KEY. Restart your client and ask it to use isayaction and discover its tools. Claude Desktop and claude.ai custom connectors require OAuth, which is not provided in this release.

3. Organize the script into episodes and shots

Start with get_account and list_models to read your balance and available model capabilities. Use list_projects or create_project, then list_canvases or create_canvas. Read canvas_list_node_types and canvas_get_state before canvas edits; supported writes use the latest snapshotHash.

Ask the external Agent to split your source script into episodes first. import_script imports units already prepared by the Agent; it does not run a model to split text. list_units and get_unit_workspace help the Agent inspect the result. set_unit_shots can initialize an empty episode; create_shot and revise_shot handle subsequent shot work.

Example user request: Use isayaction to create a 9:16 short drama project called Night Train. Split the script below into one episode with three shots. Preserve the dialogue, describe framing and camera movement, create a canvas storyboard with canvas_create_storyboard, and return get_canvas_link. Provide distinct idempotencyKey values for each creation, such as night-train-project-001 and night-train-storyboard-001; reuse each key on retries. Do not submit media generation yet. [Paste your script here.]

Expert-profile follow-up (reconnect with ?profile=expert): Read the actual storyboard row IDs with canvas_read_storyboard. Change the second shot to a close-up, keep its dialogue, and update it with canvas_edit_storyboard using the current snapshotHash and idempotencyKey=night-train-edit-001. Return the updated canvas link.

4. Generate a small batch of first frames

Character management requires expert profile and projects:read/write. Create or inspect project characters with create_character, list_characters and get_character. set_character_representations can attach ready reference images; it does not generate them. In the default workflow, use existing owned reference node IDs from canvas_get_state. Discover a supported image model with list_models and reuse references when the model supports them.

Example user request: Generate one first-frame image for each of these three storyboard shots using the available image model I selected. Reuse the owned reference node IDs wherever supported. Use generate_media with idempotencyKey=night-train-shot-001 (a distinct key for each shot), report the charged estimate and task IDs, wait with wait_generations(mode=all, waitSeconds=50), and return the results and get_canvas_link. My key spending limit is already configured.

wait_generations accepts 1–20 task IDs; waitSeconds=0 and includeResults=false return a compact status summary. Omitted includeResults preserves full outputs. Default any mode returns immediately when a supplied ID is already terminal, so remove finished IDs before waiting again. Failed and cancelled tasks are terminal too.

generate_media submits a paid task immediately and returns taskId plus the charged estimate. Every task, paid call and object/revision creation requires an 8-128 character idempotencyKey. Retries must reuse the same key and identical arguments; changing its parameters requires a new key. An external canvas session can remain busy while a submitted task finishes its node write-back, so wait for the result before continuing writes. Query failures before deciding to retry: retry_generation can create a new billable attempt.

Open the returned canvas link and sign in to review results. Tasks run on the server without an open browser; open canvases discover external updates, while background tabs and network delays can postpone synchronization. First frames are images, not finished video clips.

5. Continue only after reviewing the result

You can request video generation from reviewed frames where the selected model supports the required controls. render_timeline (for example with idempotencyKey=night-train-render-001) assembles available owned resources using a timeline request; it does not generate missing clips. Use get_generation for its returned taskId. A script-to-video MCP workflow still depends on successful media tasks and valid resource references.

Alternatively, use agent_start with idempotencyKey=night-train-agent-001 to delegate a brief to the built-in Agent and agent_get_run to inspect progress, tasks and spend. The default Agent credit budget is 200 credits; you can specify a smaller budget. MCP-authorized media approval is automatic, so configure your key limit before delegating.

Use the MCP setup link below to review connection and billing details. Read the script-to-storyboard guide at /blog/script-to-storyboard and pricing at /pricing, or return to the AI storyboard workspace from the Home link. Expand the shot count only after checking the first batch.

Connect your own API channels and third-party relays

In model-channel settings, enter the Base URL and API key, then configure the protocol, model IDs and required headers from your provider's documentation. Check the image and video modes you need before generating. Paths, resolutions and first/last-frame inputs depend on the connected channel. An adaptation request for an unsupported channel is not a compatibility guarantee.

BYOK supports a custom API endpoint, model key and headers. For OneAPI, NewAPI or another relay, select the OpenAI, Gemini or Claude protocol that matches its actual API, then check model IDs and image/video endpoint support. Not every relay or private protocol works automatically. BYOK model calls have no platform model markup or platform generation-credit deduction; workspace access and provider usage are still billed separately.

Connect only trusted providers and use HTTPS in production. Custom requests are forwarded through the authenticated backend; required prompts, reference assets and credentials take part in the request. Never put API keys, passwords or secret-bearing headers in public canvases, screenshots or support requests.