MCP server documentation

Last updated: October 9, 2026

The Raylight MCP server lets an AI assistant work inside your Raylight project: read the shots, make edits, upload media, and render real frames to check its own work. It follows the Model Context Protocol, so it works with Claude (web, desktop, mobile, and Claude Code), ChatGPT and Codex, Cursor, and any other MCP client. For a guided setup with copy-paste prompts, see the connect page.

Server URL

https://api.raylight.app/mcp

Transport is streamable HTTP. Enter the URL exactly as written when a client asks for it.

What you need

  • A Raylight account. Signup is free, and you can create the account from the connector's consent screen the first time you connect.
  • For editing and rendering, the project open in your browser at raylight.app. The tab can sit in the background, but it has to stay open. Listing projects and templates, reading the design guide, uploading media, and checking exports work without an open tab.

Connect

Claude (web, desktop, mobile)

Open Settings, then Connectors. If Raylight is in the directory, pick it there. Otherwise choose Add custom connector, paste the server URL, click Add, then Connect, and approve the Raylight sign-in.

Claude Code

Run claude mcp add --transport http raylight https://api.raylight.app/mcp, then /mcp to complete the sign-in in your browser.

ChatGPT

Turn on Developer mode (Settings, Connectors, Advanced), create a custom connector with the server URL and OAuth authentication, and approve the Raylight sign-in.

Codex, Cursor, and other clients

Add a streamable HTTP MCP server named raylight with the URL above in the client's MCP settings or config file. Every client that supports OAuth for MCP will open the Raylight sign-in when it first connects.

Authentication

The server uses OAuth 2.0 with PKCE. Your AI client never sees your Raylight password: it sends you to a Raylight page that names the app asking for access, the scopes it requested, and where you will be sent back after approving. You approve or deny, and the client receives a token scoped to your account. Tokens refresh automatically. API keys made for the REST API are not accepted on the MCP server.

To disconnect, remove the connector in your AI client. To revoke every connection at once, email cyrus@raylight.app.

Tools

Read tools never change anything and run without confirmation in clients that honor tool annotations. Write tools change your project; every change lands in your open editor, shows up on the canvas as it happens, and can be undone there like your own edits.

Read

  • get_editor_status: Is an editor tab connected, and to which project.
  • list_projects: Your projects with an edit link for each, plus projects shared with you.
  • get_project_overview: The whole project: shots, coordinate system, colors and fonts, media.
  • get_shot_details: One shot in full: every layer, animation, camera move, and sound.
  • render_stills: Real rendered frames at chosen times, with layer positions for checking.
  • render_filmstrip: A strip of frames across a span, to read pacing at a glance.
  • render_waveform: The mix as a waveform and spectrogram, with visual beats marked.
  • check_sync: Exact offsets between sounds and the visual beats they should hit.
  • get_design_guide: Raylight's craft rules and template beat sheets.
  • list_templates: Official templates to start from.
  • list_videos: Your exported videos and their share pages.
  • get_import_report: What an After Effects import kept editable and what it flattened.
  • get_import_status: After Effects imports you started but have not finished.
  • get_editor_capabilities: This list, from the server itself.

Write

  • apply_edits: Up to 200 edits in one call: add and animate layers, cameras, lights, frames, sound, effects.
  • upload_media: Put an image, video, or audio file into the project's asset library.
  • start_from_template: Create a new project from an official template.
  • save_as_video: Turn a design-mode canvas into a video project.
  • update_share_page: Set the title, description, and look of an exported video's share page.
  • file_shared_project: Choose which of your workspaces a project shared with you shows up in.
  • score_import_fidelity: Measure how closely an imported project matches After Effects, frame by frame.
  • discard_import_session: Throw away an unfinished After Effects import. The only destructive tool.

Example prompts

  • “Check my Raylight editor connection and describe the project I have open.”
  • “Make the headline slide up over half a second and add a slow push-in, then render the first shot to check it.”
  • “Here are three screenshots of my app. Start from a launch template and swap them in.”
  • “Score every cut with a deep cinematic whoosh and show me the waveform.”
  • “The second shot feels slow. Tighten it and render a filmstrip so I can see the pacing.”
  • “Match the colors and fonts of the first shot across the whole project.”

What to expect

  • The assistant reads a shot before editing it, batches its edits, then renders frames and fixes what reads wrong. Expect a few tool calls per request and a visible result on your canvas within seconds.
  • Renders are the real renderer, not a preview. What you see in a still is what exports.
  • Exports and share links are made from Raylight. The assistant can list them and customize share pages; it cannot publish anything publicly on its own.

Limits

Tool calls are metered per ISO week by plan. New Free and Hobby accounts start with a one-time trial bucket of 1,000 calls that never counts against a week, so the first projects are never interrupted.

  • Free: 50 tool calls per week
  • Hobby: 1,000 tool calls per week
  • Pro: 5,000 tool calls per week
  • Max: Unlimited

Over the cap, calls draw two credits each from your credit balance, and a credit pack unblocks you immediately. Results start carrying a short usage note at 70% of the weekly allowance.

  • Media uploads: up to 100 MB per file fetched from a URL, 5 MB inline. Images, mp4, webm, mov, mp3, wav, m4a, aac.
  • Call timeouts: 60 seconds for reads, 3 minutes for renders, 4 minutes for an edit batch. A timeout almost always means the editor tab was closed or the laptop went to sleep; reopen the project and retry.
  • Up to 200 edits per apply_edits call, 50 projects per listing.
  • After Effects imports need the Raylight panel installed in After Effects; the assistant can read and score an import but cannot start one.

Privacy

The server reads and writes only the Raylight account that approved the connection. For each tool call it records the tool name, duration, and outcome so we can keep the connector reliable; it never records your conversation with the assistant. Project content moves between your editor tab and your AI client through the server and is stored only as part of your project, the same as edits you make by hand. Media you upload lands in your project's asset library. The full policy is at raylight.app/privacy.

Support

Email cyrus@raylight.app. Include the client you are using, the project link, and roughly when the call failed; the connector logs are keyed by time and tool, so that is enough to find it.