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. Connect your AI

Open Settings → Connect your AI and choose your agent. No API key is needed for the hosted connection. You can connect and read your workspace before subscribing; creating, editing, and generating require an active plan.

• Cursor: select Connect to Cursor and approve adding the server.
• Claude: copy the server URL into Settings → Connectors → Add custom connector, name it Sundream, and connect. If asked, choose automatic registration.
• Claude Code: copy and run the setup command, then open /mcp to sign in.
• Codex: select Open Codex to review a setup prompt, or run the commands below. Send the prompt yourself to start setup.
• Other agents: add the server URL as a remote HTTP MCP connection with OAuth. The Copy setup prompt button asks a capable agent to configure it and install the optional skill for you.

codex mcp add sundream --url https://api.sundream.studio/mcp
codex mcp login sundream

claude mcp add --transport http sundream https://api.sundream.studio/mcp

2. Approve access

When your agent opens Sundream in the browser, sign in, choose the workspace, and set a daily credit limit. Only owners and admins can authorize access. The limit applies over a rolling 24 hours, and render approval starts in Confirm each render mode. Review the requesting agent and callback address before approving.

Your agent receives credentials for this workspace's MCP connection. It cannot manage account credentials or billing. Revoke access or change its limit in Settings → Connect your AI at any time. The access list shows Authorized · waiting for agent until an authenticated MCP request succeeds.

The optional Sundream skill adds filmmaking guidance. Install it in your client's standard skill folder; for a local Codex project, use .agents/skills/sundream/SKILL.md and start a new session. The connection itself already includes workflow instructions. A portable plugin bundle includes both the skill and remote MCP configuration for clients that accept local plugins. It is not yet listed in the public plugin directory.

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

The hosted MCP connection returns media URLs. For local file synchronization, use the optional local bridge with a manually managed API key. Create the key under Settings → Connect your AI → Manual API key, then set SUNDREAM_API_KEY in the environment that launches your client. Keep the key out of committed configuration files and chat.

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

Renders run in the background. Use checkGenerations for progress, or checkGenerations with waitSec 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

• Sign-in does not open: check that your client supports remote HTTP MCP and OAuth. Use the copied URL or setup commands.
• Expired authorization: start the connection again in your agent.
• No API key (local bridge): 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.