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
The LyricWinter MCP server exposes 13 tools. Read-only tools need the studio:read scope; tools that create or change Studio content need studio:write. Every tool calls the LyricWinter REST API as the connected user and returns its JSON response as text.
Recommended agent workflow#
The server gives agents these instructions: 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_projectsto find the project, orcreate_storyto start a new one.get_documentto read the script and its versions.start_audio_workflowafter the user confirms which sections to generate.get_workflowuntil the run reachescompleted,partially_completed,failed, orcancelled.get_section_mediaorget_playback_manifestto return playable audio.
Tool summary#
| Tool | Purpose | Scope | Side effects |
|---|---|---|---|
profile | Identify the connected account | studio: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#
A successful tool returns 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. |