Scenaloom MCP tools reference
This is every tool the Scenaloom MCP server offers a connected AI app, with the permission each one needs. Tool names and the descriptions the app reads are in English; the app answers you in your language. To connect an app, see Connect Scenaloom to AI apps.
Tools
| Tool | Permission | What it does |
|---|---|---|
| list_projects | Read | Lists the writer's Scenaloom projects (their own and shared with them), newest edit first. Filter by words in the title or description, or by type. Returns ids for the other tools and an app_url to open each one. Scope: projects:read; needs the viewer role or above in the project. |
| get_project | Read | One project's overview: title, description, type, your role, its episodes (scene and character counts) and how many characters, locations and props it has. Scope: projects:read; needs the viewer role or above in the project. |
| read_script | Read | Reads an episode of a screenplay as numbered blocks (scene_heading, action, character, dialogue, parenthetical, transition, shot...). Each block has a node_id and node_hash; the result has the document_hash. Pass those to propose_script_edits. Page with from_index, or read one scene by its number. format "fountain" also returns the window as Fountain text. Scope: projects:read; needs the viewer role or above in the project. |
| list_scenes | Read | The scenes of one episode in order: number, heading, location, time of day and the block index where each starts (use with read_script's scene or from_index). Scope: projects:read; needs the viewer role or above in the project. |
| list_entities | Read | The project's characters, locations or props with their metadata (a character's gender, age and occupation; a location's scouting status), their detail fields (bio, appearance, description...), scene counts and, for characters, their relations. Scope: projects:read; needs the viewer role or above in the project. |
| get_story_structure | Read | The project's beat sheet (with its target length), its story outline and, for a series episode, that episode's outline. Scope: projects:read; needs the viewer role or above in the project. |
| read_novel | Read | Lists a novel's chapters (number, title, length) and, when a chapter number is given, returns its text (up to limit_chars from offset) and outline. The result's rev is the base_rev for propose_novel_edits. Reads the latest words, including what collaborators typed seconds ago. Scope: projects:read; needs the viewer role or above in the project. |
| search_project | Read | Finds words in a project: its script (every episode, up to 20), novel chapters, characters/locations/props, comments and beats. Case-insensitive, works for any language. Each hit says where it is (episode and block index, or chapter) with a short snippet. Scope: projects:read; needs the viewer role or above in the project. |
| list_comments | Read | Comments on one episode's script (or its scene board): author, whether AI wrote it, the line it is anchored to, text, resolved state and replies. Scope: projects:read; needs the viewer role or above in the project. |
| list_generations | Read | The writer's paid generations (images, video, audio), newest first, with status, credits and result links. Filter by project or status. Scope: projects:read; needs the viewer role or above in the project. |
| get_generation | Read | The status of one generation started with start_generation (or in the app): Pending, Running, Completed (with result_url), Failed (refunded) or Cancelled. Poll every 10-30 seconds; videos take minutes. Scope: projects:read; needs the viewer role or above in the project. |
| propose_script_edits | Edit | Proposes up to 6 edits to one episode of a screenplay without changing it, anchored to what you read with read_script: pass its document_hash, and the node_id and node_hash of the line you are working at (rewrite_line rewrites that line; insert_action goes after it). Returns a proposal_id and before/after previews. Show the previews to the writer and call apply_script_edits only after they agree. The proposal also appears in the writer's AI panel in Scenaloom and expires after 30 minutes. Scope: scripts:write; needs the editor role or above in the project. |
| apply_script_edits | Edit | Applies a proposal from propose_script_edits, after the writer agreed to it. Refused if the anchored line or the script changed since (read again and propose again). Live collaborators see the change at once; the episode as it was is kept in the app's Version history, and the edits can be undone with undo_script_edits (batch_id). Calling it again for the same proposal returns the same result. Scope: scripts:write; needs the editor role or above in the project. |
| undo_script_edits | Edit | Undoes a batch of edits applied with apply_script_edits (or from the AI panel). Later edits elsewhere in the episode are kept; it is refused only when a later edit changed or removed a line these edits wrote, so nobody's newer work is lost. Then the writer can restore the version from before the edits in the app's Version history. Scope: scripts:write; needs the editor role or above in the project. |
| propose_novel_edits | Edit | Proposes up to 10 edits to one chapter of a novel without changing it: replace exact words (each find must appear exactly once in the chapter) or append text. Pass base_rev, the rev from read_novel. Returns a proposal_id and previews; show them to the writer and call apply_novel_edits only after they agree. Expires after 30 minutes. Scope: scripts:write; needs the editor role or above in the project. |
| apply_novel_edits | Edit | Applies a proposal from propose_novel_edits, after the writer agreed. It re-reads the latest words (including live typing), checks every find is still there exactly once, and saves through the novel's normal save, which merges with what collaborators are typing. Each save is kept in the novel's version history, where the writer can restore an earlier version. Scope: scripts:write; needs the editor role or above in the project. |
| undo_novel_edits | Edit | Takes applied novel edits back out of their chapter, keeping writing added since; refused if someone wrote into the edited words. |
| update_entity | Edit | Changes a character's, location's or prop's details. Refused if someone changed the entry since it was read; the writer can undo it from the AI panel for a day. |
| undo_entity_update | Edit | Takes back a change update_entity made, while those fields still read as it left them. |
| create_project | Edit | Creates a new, empty screenplay or novel in the writer's account (their plan's project limit applies). Retrying with the same request_id returns the same project. Scope: scripts:write; needs the editor role or above in the project. |
| create_episode | Edit | Adds the next episode to a series screenplay (films have one). Retrying with the same request_id returns the same episode. Scope: scripts:write; needs the editor role or above in the project. |
| add_comment | Comment | Leaves a comment on a script line (anchor.node_id from read_script) or on the episode, marked as written by this app. @mentions of collaborators send them email only when notify_mentions is true and the writer confirms it; otherwise the comment is saved without notifying anyone. Retrying with the same request_id doesn't add it twice. Scope: comments:write; needs the commenter role or above in the project. |
| resolve_comment | Comment | Marks a comment thread resolved (or reopens it). A commenter can resolve only their own threads; editors can resolve any. Scope: comments:write; needs the commenter role or above in the project. |
| get_credits | Spend credits | The writer's credit balance, this app's spending rule (never, ask each time, or a daily cap), the cap and what this app spent in the last 24 hours. Scope: ai:use; needs the editor role or above in the project. |
| quote_generation | Spend credits | Prices a paid generation (a character portrait, a location image, a storyboard frame, a video shot...) without starting it or spending anything. Returns a quote_id valid for 5 minutes and usable once. Tell the writer the cost, then call start_generation. Scope: ai:use; needs the editor role or above in the project. |
| start_generation | Spend credits | Starts a quoted generation and spends the quoted credits. Never call this without the writer's explicit approval of the quoted cost. When the client can show a confirmation, the writer is asked here. Otherwise it runs only if the writer set a daily credit cap for this app and you pass confirm: true after they approved in the conversation. Either way, a daily cap the writer set is never exceeded (mcp.dailyCapReached). Retrying with the same request_id doesn't start or charge twice. Poll the result with get_generation. Scope: ai:use; needs the editor role or above in the project. |
| cancel_generation | Spend credits | Asks the provider to stop a running generation. Credits are refunded when the provider confirms the cancellation; some providers can't stop a job once it started. Scope: ai:use; needs the editor role or above in the project. |
Read tools never change anything. Edit tools change your work only through a proposal you approved, and every applied batch can be undone. The only tool that spends credits is start_generation, and only after you confirm the quoted cost.
How an edit works
- The app reads the scene with read_script, which returns each block with its id and the script's revision.
- It calls propose_script_edits with up to six changes. Scenaloom checks them and returns a before and after preview of each; the proposal waits 30 minutes and also shows in the editor's AI panel.
- The app shows you the previews. When you agree, it calls apply_script_edits. If someone changed the script in between, the apply is refused and the app reads again.
- The result lists the batch id. undo_script_edits with that id reverses the batch, and version history keeps the earlier draft either way.
Novels work the same way with read_novel, propose_novel_edits and apply_novel_edits: each passage to replace must appear exactly once in the chapter, so an edit can never land in the wrong place.
How a generation is paid for
- quote_generation prices the request without spending anything and returns a quote that is valid for five minutes and can be used once.
- The app tells you the cost and your balance after it, and calls start_generation only when you agree. Apps that support confirmations show you Scenaloom's own confirmation; other apps can spend only within the daily cap you set.
- get_generation reports progress and the result. If the price changed after the quote, Scenaloom refuses to start, and a failed generation is refunded under the Credits Policy.
Resources and prompts
Apps that browse resources can attach a project, an episode as Fountain, a novel chapter or the project's story bible (characters, locations, props, relationships, beats and outline) to a conversation. Prompts start common jobs: a script doctor pass, beat structure notes, a scene revision, table read notes, and a logline and synopsis. The prompt titles follow your Scenaloom interface language.
Errors an app may report
| Message | What to do |
|---|---|
| The script changed after the proposal | Read the scene again and propose again. |
| Insufficient scope | The app lacks a permission. Disconnect it under Connected apps, then connect it again and tick the permission. |
| Not found | The project was deleted, or you no longer have access to it. |
| This app can't confirm spending | Set a daily credit cap for the app, or start the generation in Scenaloom. |
| Rate limited | Wait the number of seconds given, then retry. |