Connect an agent

You'll need a Sundream workspace, an owner or admin role, and an MCP client. The local bridge also needs Node.js 20 or newer with npx available.

1. Create an API key

Open Settings → API keys and name a new key after the client or task that will use it. Choose a render-approval mode and, optionally, a spending cap in credits over a rolling 24 hours.

Start with Confirm each render while you check the setup. This returns a quote before a render starts; your agent submits the approval.

Copy the key when it's shown. You can't retrieve it later. If you lose it, revoke it and create a replacement.

2. Connect your client

Set SUNDREAM_API_KEY in the environment used to launch your client. Replace the placeholder with the key you just created:

export SUNDREAM_API_KEY="YOUR_API_KEY"

For Claude Code, register the local bridge:

claude mcp add \
  --transport stdio sundream -- \
  npx -y @sundream-studio/mcp \
  --media-dir ./assets

Start Claude Code from the same environment so the bridge can read the key. If you launch your client another way, configure SUNDREAM_API_KEY in that client's MCP server environment. Keep the value out of committed config files.

For other clients, use npx as the command. Pass -y, @sundream-studio/mcp, --media-dir, and ./assets as separate arguments.

For a remote connection, use the MCP endpoint shown on the API keys page and send your key as a bearer token in the Authorization header.

3. Check the connection

Ask your agent to call listProjects. It should return your workspace's projects, or an empty list if you haven't created one. This check doesn't start a generation.

In Claude Code, use /mcp to check the server status. Its MCP setup guide covers client-specific configuration and troubleshooting.

4. Plan a film

Ask for a film and describe the subject, length, aspect ratio, and style. For example:

Plan a 20-second vertical film about a night train. Use quiet station sounds and no dialogue. Show me the scenes and a cost estimate before rendering.

Sundream also provides a new-film MCP prompt for guided planning. Look for it in your client's prompt menu; the command name depends on the client.

Ask for estimateCost after the board is ready, then agree on the work and budget. Keys and spending explains approval modes.

5. Download the media

Renders run in the background. Use checkGenerations for progress or waitForGenerations to wait for completion. With --media-dir configured, ask the agent to call syncProjectMedia with the project's ID.

Files use the same folder structure as a project download. Calling sync again skips files already present on disk.

Troubleshooting

• No API key: check that the bridge's environment contains SUNDREAM_API_KEY.
• Invalid key: check whether the key was revoked or its creator left the workspace. Create a replacement if needed.
• No local sync tool: add --media-dir and reconnect the client.
• Generation won't start: ask for whatsNext to see missing references, pending approvals, or other blockers.