MCP server

LyricWinter MCP tools reference

Every tool exposed by the LyricWinter Studio MCP server, with inputs, required scopes, side effects, and the recommended agent workflow.

BetaUpdated September 30, 2026

Markdown Ask ChatGPT Ask Claude

The LyricWinter MCP server exposes 22 tools. Read-only Studio tools need the studio:read scope; tools that create or change Studio content need studio:write. Voice tools need voices:read or voices:write. Every tool calls the LyricWinter REST API as the connected user.

In ChatGPT, Claude, and other chat apps#

Chat apps that support interactive MCP Apps show a story player and a voice panel inside the conversation. The server tells the model to call create_audio_story once with the full story text: the player shows casting and generation progress, then plays the finished audio with the script. Use play_story to reopen a story, share_story for a public link, find_voices with recast_character to change a character's voice, and add_my_voice when the user wants their own voice. Listing tools and loading the widgets works before an account is linked; every tool that reads or changes an account asks the user to connect LyricWinter.

Recommended workflow for coding agents#

For advanced work on existing Studio projects, use list_projects and list_project_sections to find IDs, read documents before changing them or generating audio, treat workflow starts as asynchronous and call get_workflow until they finish, and never repeat a paid audio start unless the user wants another run.

A typical session:

list_projects to find the project, or create_story to start a new one.
get_document to read the script and its versions.
start_audio_workflow after the user confirms which sections to generate.
get_workflow until the run reaches completed, partially_completed, failed, or cancelled.
get_section_media or get_playback_manifest to return playable audio.

Tool summary#

Tool	Purpose	Scope	Side effects
`profile`	Identify the connected account	`studio:read`	None
`create_audio_story`	Turn story text into fully cast audio with a player	`studio:write`	Creates content, consumes words
`play_story`	Open the player for an existing story	`studio:write`	Prepares an MP3 mix
`share_story`	Create a public listening link	`studio:write`	Publishes the story
`find_voices`	Search the voice library or the user's voices	none, or `voices:read`	None
`recast_character`	Change a character's voice and regenerate their lines	`studio:write`, `voices:read`	Changes casting, consumes words
`add_my_voice`	Open the voice panel to add the user's own voice	`voices:write`	None until the user uploads
`get_story_state`	Player only: refresh progress and the audio URL	`studio:write`	Prepares an MP3 mix
`upload_voice_sample`	Voice panel only: create a private voice from a sample	`voices:write`	Creates a voice
`get_voice_status`	Voice panel only: check voice processing	`voices:read`	None
`list_projects`	List projects and standalone stories	`studio:read`	None
`list_project_sections`	List a project's sections in order	`studio:read`	None
`get_document`	Read a section's document	`studio:read`	None
`list_project_speakers`	List a project's speakers	`studio:read`	None
`create_story`	Create a standalone story	`studio:write`	Creates content
`create_section`	Add a section to a project	`studio:write`	Creates content
`prepare_sections`	Structure sections into a script	`studio:write`	Changes documents
`start_audio_workflow`	Generate audio	`studio:write`	Consumes words
`get_workflow`	Check workflow progress	`studio:read`	None
`cancel_workflow`	Cancel a running workflow	`studio:write`	Stops work
`get_section_media`	Get per-block audio for a section	`studio:read`	None
`get_playback_manifest`	Get the compiled playback timeline	`studio:read`	None

Results and errors#

The chat-app tools (create_audio_story, play_story, share_story, find_voices, recast_character, add_my_voice) return a short summary for the model as structuredContent; the full script, line timings, and signed audio URL go only to the player in _meta. The other tools return the REST API's JSON response, including data and request_id. Tools that accept a mutation_id wrap it as { "result": ..., "mutation_id": "..." } so the agent can retry the same change. A failed tool sets isError and returns the API error, plus the mutation_id when there is one. If LyricWinter could not confirm whether a write happened, the error says "No result was confirmed"; retry with the same mutation_id.

Account#

`profile`#

Identifies the connected LyricWinter account. Returns id, name, and email as structured content. Takes no input.

Projects and sections#

`list_projects`#

Lists the user's Studio projects and standalone stories with their IDs. Takes no input. Calls GET /studio/projects.

`list_project_sections`#

Lists the sections of one project in order, including each section's ID and the project's section_order_version. Calls GET /studio/projects/{projectId}/sections.

Input	Type	Required	Description
`project_id`	UUID	Yes	The project to list.

`create_story`#

Creates a standalone Studio story from text. Calls POST /studio/sections.

Input	Type	Required	Description
`title`	string, 1–500 characters	Yes	Story title.
`raw_text`	string, 1–100,000 characters	Yes	The story text.
`mutation_id`	UUID	No	Reuse only when retrying the exact same creation. Generated if omitted.

`create_section`#

Adds a section to an existing project. Read the project's sections first to get its current section_order_version. Calls POST /studio/projects/{projectId}/sections.

Input	Type	Required	Description
`project_id`	UUID	Yes	The project to add to.
`base_section_order_version`	integer or null	Yes	The `section_order_version` from `list_project_sections`.
`title`	string, 1–500 characters	Yes	Section title.
`raw_text`	string, 1–100,000 characters	Yes	The section text.
`mutation_id`	UUID	No	Reuse only when retrying the exact same creation.

Documents and speakers#

`get_document`#

Reads a section's current document: its version, blocks, speakers, and edit targets. Agents should read the document before generating audio. Calls GET /studio/sections/{sectionId}/document.

Input	Type	Required	Description
`section_id`	UUID	Yes	The section to read.

`list_project_speakers`#

Lists the speakers used in a project and their casting status. Calls GET /studio/projects/{projectId}/speakers.

Input	Type	Required	Description
`project_id`	UUID	Yes	The project to inspect.

Workflows#

`prepare_sections`#

Starts an asynchronous workflow that structures sections into narration and dialogue without generating audio. Poll get_workflow for completion. Calls POST /studio/projects/{projectId}/workflows with workflow_kind: "prepare_sections".

Input	Type	Required	Description
`project_id`	UUID	Yes	The project that owns the sections.
`section_ids`	array of UUIDs, 1–100	Yes	Sections to prepare.
`mutation_id`	UUID	No	Reuse only when retrying the same request.

`start_audio_workflow`#

Starts the paid, asynchronous Create Audio workflow for selected sections. It prepares text, casts voices, directs performances, adds sound effects, and generates audio. Confirm the scope and cost with the user first, then poll get_workflow. Calls POST /studio/projects/{projectId}/workflows with workflow_kind: "create_audio".

Input	Type	Required	Description
`project_id`	UUID	Yes	The project that owns the sections.
`section_ids`	array of UUIDs, 1–12	Yes	Sections to generate.
`include_generated_sfx`	boolean	No	Add AI-generated sound effects. Defaults to `true`.
`place_project_sounds`	boolean	No	Place sounds linked to the project. Defaults to `true`.
`mutation_id`	UUID	No	Reuse only when retrying the same run. A new ID starts a new, separately billed run.

`get_workflow`#

Returns a workflow's status, current stage, step progress, warnings, and errors. Calls GET /studio/workflows/{workflowRunId}.

Input	Type	Required	Description
`workflow_id`	UUID	Yes	The `run.id` returned when the workflow started.

`cancel_workflow`#

Requests cancellation of a running workflow. Agents should ask the user before cancelling. Calls POST /studio/workflows/{workflowRunId}/cancel.

Input	Type	Required	Description
`workflow_id`	UUID	Yes	The workflow to cancel.

Media and playback#

`get_section_media`#

Returns the generated audio state of every block in a section, with short-lived signed playback URLs. Calls GET /studio/sections/{sectionId}/media.

Input	Type	Required	Description
`section_id`	UUID	Yes	The section to inspect.

`get_playback_manifest`#

Returns the compiled playback timeline for a section. Pass the versions returned by get_document. Calls GET /studio/sections/{sectionId}/playback-manifest.

Input	Type	Required	Description
`section_id`	UUID	Yes	The section to play.
`document_version`	integer	Yes	`document.document_version` from `get_document`.
`speaker_registry_version`	integer	Yes	`document.speaker_registry_version` from `get_document`.

Listening in chat apps#

`create_audio_story`#

Turns a story, fanfic, script, or chapter into fully cast audio. Creates a standalone story (POST /studio/sections) and starts Create audio, which detects characters, casts voices, directs the performances, and adds sound. Returns the story player, which tracks progress on its own. Uses words from the user's balance.

Input	Type	Required	Description
`story_text`	string, 1–100,000 characters	Yes	The complete story text.
`title`	string, 1–200 characters	No	Story title. Derived from the first line if omitted.
`sound_effects`	boolean	No	Add ambient sound and sound effects. Defaults to `true`.

`play_story`#

Opens the player for a story the user already made. Prepares an MP3 mix of the current audio when needed.

Input	Type	Required	Description
`section_id`	UUID	No	The story to open. Defaults to the user's most recent story.

`share_story`#

Publishes a story and returns its public listening link. Anyone with the link can listen and read the script. Calls POST /studio/sections/{sectionId}/share.

Input	Type	Required	Description
`section_id`	UUID	Yes	The story to share.

Voices#

`find_voices`#

Searches LyricWinter's public voice library, or the user's own voices, and returns voice IDs for recast_character. Library search works without a linked account.

Input	Type	Required	Description
`query`	string, up to 200 characters	No	Words describing the voice, or a voice name.
`mine`	boolean	No	Search only the user's voices. Requires a linked account.

`recast_character`#

Changes a character's voice with Studio's preferred engine for that voice, then regenerates the character's lines unless told not to.

Input	Type	Required	Description
`section_id`	UUID	Yes	The story.
`character`	string	Yes	The character's name as shown in the cast.
`voice_id`	UUID	Yes	A voice from `find_voices`.
`regenerate_audio`	boolean	No	Regenerate the changed lines. Defaults to `true`.

`add_my_voice`#

Opens the voice panel, where the user records or uploads a 10–30 second sample of their own voice and confirms they have permission to use it. The new voice is private.

Input	Type	Required	Description
`voice_name`	string, 1–80 characters	No	Suggested name for the voice.

Player and voice panel#

These tools are called by the widgets and hidden from the model.

`get_story_state`#

Refreshes a story's progress, cast, script timings, and signed audio URL.

Input	Type	Required	Description
`section_id`	UUID	Yes	The story.
`workflow_id`	UUID or null	No	The Create audio run to track.

`upload_voice_sample`#

Creates a private voice from the user's sample through the same upload flow as LyricWinter's apps.

Input	Type	Required	Description
`name`	string, 1–80 characters	Yes	Voice name.
`mime_type`	string	Yes	The sample's audio type, such as `audio/webm`.
`data_base64`	string	Yes	The sample, base64-encoded, up to 2.5 MB.
`permission_confirmed`	`true`	Yes	The user confirmed they have permission to use this voice.

`get_voice_status`#

Checks whether a new voice has finished processing.

Input	Type	Required	Description
`voice_id`	UUID	Yes	The voice to check.

In ChatGPT, Claude, and other chat apps#

Recommended workflow for coding agents#

Tool summary#

Results and errors#

Account#

profile#

Projects and sections#

list_projects#

list_project_sections#

create_story#

create_section#

Documents and speakers#

get_document#

list_project_speakers#

Workflows#

prepare_sections#

start_audio_workflow#

get_workflow#

cancel_workflow#