From 4d266bf865f66b6a66230259e373e029d8120270 Mon Sep 17 00:00:00 2001 From: Raghav Ahuja Date: Thu, 15 Oct 2026 17:32:25 -0700 Subject: [PATCH 1/4] docs(mcp): document the tools the MCP server exposes The MCP guide described what the server can do but never named a tool, even though the coding-agents page already linked to it "for the tool list". Add the list and close that gap. - Add overview/mcp/tools.mdx: the core tools grouped into voices, speech and transcription, file uploads, images and video, and account, with what each one does. - Add a Tools section to the MCP guide summarising the five groups and linking to the reference. - Note voice cloning in the guide intro, which under-sold the scope. - Nest both pages under an "MCP Server" group in the sidebar. Covers the core tool set only; Story Studio and asset library tools are not documented here. Co-Authored-By: Claude Code --- developer-guide/resources/coding-agents.mdx | 2 +- docs.json | 6 +- overview/mcp.mdx | 19 +++++- overview/mcp/tools.mdx | 65 +++++++++++++++++++++ 4 files changed, 89 insertions(+), 3 deletions(-) create mode 100644 overview/mcp/tools.mdx diff --git a/developer-guide/resources/coding-agents.mdx b/developer-guide/resources/coding-agents.mdx index f453002e..01eb8681 100644 --- a/developer-guide/resources/coding-agents.mdx +++ b/developer-guide/resources/coding-agents.mdx @@ -76,7 +76,7 @@ Once installed, ask your agent in plain language; it will use the correct client ## Or connect via MCP -The [Fish Audio MCP server](/overview/mcp) at `https://api.fish.audio/mcp` gives your agent tools instead of docs: it can search the voice library, generate speech, and transcribe audio with your Fish Audio account (OAuth sign-in, no API key). See the [MCP server guide](/overview/mcp) for client setup and the tool list. +The [Fish Audio MCP server](/overview/mcp) at `https://api.fish.audio/mcp` gives your agent tools instead of docs: it can search the voice library, generate speech, and transcribe audio with your Fish Audio account (OAuth sign-in, no API key). See the [MCP server guide](/overview/mcp) for client setup and the [tool list](/overview/mcp/tools) for what the agent can call. This site also exposes [llms.txt](https://docs.fish.audio/llms.txt) and [llms-full.txt](https://docs.fish.audio/llms-full.txt) for agents that fetch docs directly. diff --git a/docs.json b/docs.json index 201fe319..a61f9b61 100644 --- a/docs.json +++ b/docs.json @@ -67,7 +67,11 @@ "overview/platform/create-voice/voice-design" ] }, - "overview/mcp" + { + "group": "MCP Server", + "icon": "plug", + "pages": ["overview/mcp", "overview/mcp/tools"] + } ] }, { diff --git a/overview/mcp.mdx b/overview/mcp.mdx index 37a567b4..a3c66e50 100644 --- a/overview/mcp.mdx +++ b/overview/mcp.mdx @@ -6,7 +6,7 @@ icon: "plug" import { PromptCard } from "/snippets/prompt-card.jsx"; -The Fish Audio MCP server gives AI agents direct access to your Fish Audio account: they can browse the voice library, generate speech, transcribe audio, and generate or edit images and videos for you. +The Fish Audio MCP server gives AI agents direct access to your Fish Audio account: they can browse the voice library, clone a voice, generate speech, transcribe audio, and generate or edit images and videos for you. - **Endpoint**: `https://api.fish.audio/mcp` (streamable HTTP) - **Authentication**: OAuth. Your MCP client opens a browser window, you sign in with your Fish Audio account, and choose the team the connection works in. @@ -125,6 +125,23 @@ Once connected, ask in plain language and the agent picks the right tools. Click In coding agents like Claude Code and Codex, tools compose with the shell: the agent can download generated audio, images, and videos with `curl`, upload local recordings for transcription or reference images for editing, or batch-generate a directory of scripts. +## Tools + +The core tool set is 20 tools across five areas. Agents choose them for you from a plain-language request, so the names matter mainly when you want to steer an agent to a specific step. + +| Area | Tools | What they cover | +| ------------------------ | ----- | -------------------------------------------------------------------------------------- | +| Voices | 4 | Search the voice library, read the details of a voice, create and verify a voice clone | +| Speech and transcription | 2 | Text to speech, and speech to text | +| File uploads | 2 | Temporary slots for local audio, images, and video | +| Images and video | 10 | Model discovery, price estimates, submission, and polling | +| Account | 2 | Team workspaces and credit balance | + + + Every tool the server exposes, with the exact tool names and what each one + does. + + ## Good to know - Add audio tags in square brackets inside the text to control delivery: `[whispering]`, `[excited]`, `[laughing]`. Tags are performed, never spoken. diff --git a/overview/mcp/tools.mdx b/overview/mcp/tools.mdx new file mode 100644 index 00000000..e9514645 --- /dev/null +++ b/overview/mcp/tools.mdx @@ -0,0 +1,65 @@ +--- +title: "MCP Tools" +sidebarTitle: "Tools" +description: "Every tool the Fish Audio MCP server exposes: voices and voice cloning, speech, transcription, file uploads, and image and video generation" +icon: "wrench" +--- + +This page lists the core tools that the [Fish Audio MCP server](/overview/mcp) exposes. You rarely need the names: ask for what you want in plain language and the agent picks the tools and the order to run them in. Naming a tool is still useful when you want to steer it, for example: "Estimate the video first with `estimate_video_generation`." + +## Account + +| Tool | What it does | +| -------------------- | ------------------------------------------------------------------------------------------------ | +| `get_credit_balance` | Your plan, remaining package credits, and the maximum text length allowed in one speech request. | +| `list_my_workspaces` | The workspaces (teams) this connection can act in. | + +## Voices + +| Tool | What it does | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `search_voices` | Searches the public voice library by keyword, or browses the popular voices for a language. Results include voice IDs, tags, and sample audio. | +| `get_voice` | Everything known about one voice: description, languages, tags, popularity, a sample audio URL, and a default demo text. | +| `create_voice_clone` | Creates a voice from one to five recordings of a single speaker, given as public URLs. Ten to sixty seconds of clean speech works best, and the samples must total under 270 seconds. Creating a clone is free. | +| `verify_voice_clone` | Completes speaker verification when the server flags a clone, by submitting a recording of the speaker reading a short prompt. | + +## Speech and transcription + +| Tool | What it does | +| ---------------- | ---------------------------------------------------------------------------------------------------------------- | +| `text_to_speech` | Synthesizes text with a voice and returns a permanent audio URL. Audio tags in square brackets control delivery. | +| `speech_to_text` | Transcribes audio from a public URL. `pro` is the most accurate and `flash` costs less. | + +## File uploads + +Both tools return a temporary upload slot: the agent uploads the file, then passes the returned URL to the tool that needs it. Uploaded files are deleted automatically after 7 days. + +| Tool | What it does | +| --------------------- | --------------------------------------------------------------------------- | +| `get_upload_url` | A slot for a local audio file, so it can be transcribed. | +| `create_media_upload` | A slot for an image, video, or audio file to use as an input to generation. | + +## Images and video + +Generation is split into an estimate and a submission so that nothing is charged before you approve a price. Estimates are read-only and cost nothing. The submission re-checks the price and never charges more than the estimate you approved. + +| Tool | What it does | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `list_media_models` | The image and video models, with each model's capabilities (text-to-image, image edit, upscale, image-to-video, lip sync, and talking avatar) and default price. | +| `get_media_model` | The parameters, required input roles, and accepted file types and size limits for one model. | +| `estimate_image_generation` | Prices a text-to-image request and validates it. | +| `estimate_image_edit` | Prices an image edit or upscale and validates the input. | +| `estimate_video_generation` | Prices a video request, including image-to-video, lip sync, and talking avatars. | +| `generate_image` | Submits the image job with the parameters you approved. | +| `generate_image_edit` | Submits the edit or upscale with the parameters you approved. | +| `generate_video` | Submits the video job with the parameters you approved. | +| `get_generation_status` | Checks one or more running generations. A finished job returns its results and billing, so there is nothing more to poll. | +| `get_generation_result` | Returns the final media and billing for one generation. | + +A finished result includes a link to the item in your Fish Audio history, where you can view or download it. An image the server just generated can be reused as the input to another generation, without downloading and re-uploading it. + + + Video generation needs a Plus plan or higher. Free plans have a daily image + allowance and a smaller image count per request. The estimate reports these + limits before you are asked to approve anything. + From fb78830a37df89901855f6fea103c2db99b0b146 Mon Sep 17 00:00:00 2001 From: Raghav Ahuja Date: Thu, 15 Oct 2026 19:15:07 -0700 Subject: [PATCH 2/4] added Story Studio tools --- overview/mcp.mdx | 29 ++++++++++++++--------- overview/mcp/tools.mdx | 54 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 67 insertions(+), 16 deletions(-) diff --git a/overview/mcp.mdx b/overview/mcp.mdx index a3c66e50..2960eb7c 100644 --- a/overview/mcp.mdx +++ b/overview/mcp.mdx @@ -1,12 +1,12 @@ --- title: "MCP Server" -description: "Connect Claude, Cursor, or any MCP client to your Fish Audio account: search voices, generate speech, transcribe audio, and create images and videos" +description: "Connect Claude, Cursor, or any MCP client to your Fish Audio account: search voices, generate speech, transcribe audio, create images and videos, and produce long-form Story Studio projects" icon: "plug" --- import { PromptCard } from "/snippets/prompt-card.jsx"; -The Fish Audio MCP server gives AI agents direct access to your Fish Audio account: they can browse the voice library, clone a voice, generate speech, transcribe audio, and generate or edit images and videos for you. +The Fish Audio MCP server gives AI agents direct access to your Fish Audio account: they can browse the voice library, clone a voice, generate speech, transcribe audio, generate or edit images and videos, and produce multi-speaker [Story Studio](https://fish.audio/app/story-studio) projects for you. - **Endpoint**: `https://api.fish.audio/mcp` (streamable HTTP) - **Authentication**: OAuth. Your MCP client opens a browser window, you sign in with your Fish Audio account, and choose the team the connection works in. @@ -121,24 +121,31 @@ Once connected, ask in plain language and the agent picks the right tools. Click icon="film" prompt="Turn the image you just generated into a short video with a slow push-in, and give me the video URL and what was charged." /> + + In coding agents like Claude Code and Codex, tools compose with the shell: the agent can download generated audio, images, and videos with `curl`, upload local recordings for transcription or reference images for editing, or batch-generate a directory of scripts. ## Tools -The core tool set is 20 tools across five areas. Agents choose them for you from a plain-language request, so the names matter mainly when you want to steer an agent to a specific step. +The core tool set is 37 tools across six areas. Agents choose them for you from a plain-language request, so the names matter mainly when you want to steer an agent to a specific step. -| Area | Tools | What they cover | -| ------------------------ | ----- | -------------------------------------------------------------------------------------- | -| Voices | 4 | Search the voice library, read the details of a voice, create and verify a voice clone | -| Speech and transcription | 2 | Text to speech, and speech to text | -| File uploads | 2 | Temporary slots for local audio, images, and video | -| Images and video | 10 | Model discovery, price estimates, submission, and polling | -| Account | 2 | Team workspaces and credit balance | +| Area | Tools | What they cover | +| ------------------------ | ----- | ------------------------------------------------------------------------------------------- | +| Voices | 4 | Search the voice library, read the details of a voice, create and verify a voice clone | +| Speech and transcription | 2 | Text to speech, and speech to text | +| File uploads | 2 | Temporary slots for local audio, images, and video | +| Images and video | 10 | Model discovery, price estimates, submission, and polling | +| Story Studio | 17 | Long-form, multi-speaker projects: import and cast, edit blocks, generate audio, and export | +| Account | 2 | Team workspaces and credit balance | - Every tool the server exposes, with the exact tool names and what each one + The tools the server exposes, with the exact tool names and what each one does. diff --git a/overview/mcp/tools.mdx b/overview/mcp/tools.mdx index e9514645..8d722f74 100644 --- a/overview/mcp/tools.mdx +++ b/overview/mcp/tools.mdx @@ -1,7 +1,7 @@ --- title: "MCP Tools" sidebarTitle: "Tools" -description: "Every tool the Fish Audio MCP server exposes: voices and voice cloning, speech, transcription, file uploads, and image and video generation" +description: "Every tool the Fish Audio MCP server exposes: voices and voice cloning, speech, transcription, file uploads, image and video generation, and Story Studio" icon: "wrench" --- @@ -34,10 +34,10 @@ This page lists the core tools that the [Fish Audio MCP server](/overview/mcp) e Both tools return a temporary upload slot: the agent uploads the file, then passes the returned URL to the tool that needs it. Uploaded files are deleted automatically after 7 days. -| Tool | What it does | -| --------------------- | --------------------------------------------------------------------------- | -| `get_upload_url` | A slot for a local audio file, so it can be transcribed. | -| `create_media_upload` | A slot for an image, video, or audio file to use as an input to generation. | +| Tool | What it does | +| --------------------- | -------------------------------------------------------------------------------------------------- | +| `get_upload_url` | A slot for a local audio file or document, so it can be transcribed or imported into Story Studio. | +| `create_media_upload` | A slot for an image, video, or audio file to use as an input to generation. | ## Images and video @@ -63,3 +63,47 @@ A finished result includes a link to the item in your Fish Audio history, where allowance and a smaller image count per request. The estimate reports these limits before you are asked to approve anything. + +## Story Studio + +Story Studio is the long-form, multi-speaker side of Fish Audio: a project holds chapters, and a chapter holds blocks, one per line of narration or dialogue, each with its own voice. These tools drive the same projects as the [Story Studio editor](https://fish.audio/app/story-studio), so an edit the agent makes appears in an open editor as it works. + +Blocks and chapters are addressed by short anchors returned from an earlier read, and each block carries a revision (`rev`) that a write must quote when it changes text or voice, so two edits cannot silently overwrite each other. A block whose text or voice has changed since its audio was generated is _dirty_; only dirty blocks are regenerated, and only those are billed. + +### Projects + +| Tool | What it does | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `studio_help` | The operating manual for Story Studio, by topic: `quickstart`, `editing`, `tags`, `billing`, `errors`, and `workflows`. Worth calling before the first Studio operation. | +| `studio_list_projects` | Your Story Studio projects, newest first, with each one's chapter count and whether an import is still running. | +| `studio_project` | One project: the chapter outline with durations and dirty counts, the speaker roster, and the live state of an import or export. This is the tool to poll for both. | +| `studio_create_project` | Creates a project from the chapters and blocks you pass in, up to 200 blocks. A roster maps speaker names to voice IDs, so a block can name a character rather than a voice. Free. | +| `studio_import_document` | Imports a document or long text — novel, script, or article, up to 1.5M characters — into a new project. A background model splits it into chapters, casts a voice per speaker, and either adds delivery tags or rewrites for naturalness. Returns immediately; poll `studio_project`, and expect the project to be locked for writes until it finishes. Free. | +| `studio_update_project` | Project-wide settings: name, description, the default voice and backend for new blocks, audio defaults, a room-ambience scene preset, and chapter order. Defaults affect only blocks created afterwards. | + +### Reading and editing + +| Tool | What it does | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `studio_read_blocks` | Reads a whole chapter or a list of blocks: anchor, revision, voice, text, kind, dirty flag, and duration. `format=script` renders a read-only script view for showing a reader. | +| `studio_find` | Searches block text across a project, as a substring or a regular expression, and returns matching anchors with snippets — the way to fix something everywhere without reading every chapter. | +| `studio_write_blocks` | Applies up to 100 edits in order: update, insert, move, or delete blocks, with updates quoting the block's revision. Per-edit results report `ok`, `noop`, `conflict`, or `missing`, and a conflict returns the current text and revision to retry against. Free, and `dry_run` validates without writing. | +| `studio_create_chapter` | Adds a chapter, optionally after an existing chapter. New chapters start with one empty block. | +| `studio_update_chapter` | Renames a chapter. | +| `studio_recast_speaker` | Switches every block using one voice to another voice, project-wide, for recasting a character after an import. Free; the affected blocks become dirty. | +| `studio_enhance_text` | Polishes one block's text for speech: expands numbers, dates, symbols, and phone numbers into spoken words, and adds delivery tags at the density the Studio voices are tuned for. Free. | + +### Generating and exporting + +| Tool | What it does | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `studio_generate` | Synthesizes audio for blocks, a chapter, or the whole project. By default only dirty blocks run, since unchanged audio is reused at no cost. Quote it with `dry_run=true` first: 1 credit per UTF-8 byte of spoken text, doubled for another team's professional clone voice. Runs for up to about 45 seconds; remaining blocks continue in the background and a later call collects them. | +| `studio_list_takes` | A block's previous takes, with the exact text and voice each was generated from and whether it still matches the block's current text and voice. | +| `studio_adopt_take` | Rebinds an earlier take's audio to its block — free, no generation. Only takes that still match the block's text and voice adopt cleanly. | +| `studio_export` | Exports the project, or selected chapters, to a downloadable MP3 or WAV, optionally with subtitles. Two steps: the first call returns a quote, and a second call that confirms those credits starts the background job. Only blocks that were not yet generated are billed. Requires a paid plan. | + + + In Story Studio, editing is free and only generated audio is billed: 1 credit + per UTF-8 byte of spoken text, doubled for another team's professional clone + voice. Export requires a paid plan. + From 3ff3a39b22a85f2d04dbdba27fb46e91831d85b4 Mon Sep 17 00:00:00 2001 From: Raghav Ahuja Date: Thu, 15 Oct 2026 19:25:03 -0700 Subject: [PATCH 3/4] docs(mcp): add the Story Studio tools to the MCP reference The tools page covered the core set only, so a large part of the server's surface was missing. Document the 17 Story Studio tools in three groups (projects, reading and editing, generating and exporting), and move the guide's summary to 37 tools across six areas. Also fixes found reviewing both pages against the tool schemas: - Restore the retry-duplication warnings the tool descriptions carry. studio_create_project and studio_import_document are not idempotent, so a retried call after a client-side timeout can duplicate a project or a whole import. - Tie casting to search_voices and state the canonical sequence; the table alone left the order implicit. - Correct blocks as "paragraph or heading" (kind includes headings) and rev as required for text, voice, or audio settings, not text or voice. - Note that uploads feed transcription by URL but Studio import by storage key, and cover the web_upload_url fallback. - Say "any plan other than Free" for export, matching is_paid(). - Drop the "Every tool" claim and the duplicated cost note: the page omits the asset library and internal tools, so point at the client's own tool list as authoritative. Co-Authored-By: Claude Code --- overview/mcp.mdx | 3 ++- overview/mcp/tools.mdx | 46 ++++++++++++++++++++---------------------- 2 files changed, 24 insertions(+), 25 deletions(-) diff --git a/overview/mcp.mdx b/overview/mcp.mdx index 2960eb7c..94b16838 100644 --- a/overview/mcp.mdx +++ b/overview/mcp.mdx @@ -133,7 +133,7 @@ In coding agents like Claude Code and Codex, tools compose with the shell: the a ## Tools -The core tool set is 37 tools across six areas. Agents choose them for you from a plain-language request, so the names matter mainly when you want to steer an agent to a specific step. +The core tool set is 37 tools across six areas. Agents choose them for you from a plain-language request, so the names matter mainly when you want to steer an agent to a specific step. Your client's own tool list is what the agent actually sees, and it includes a few more tools besides these. | Area | Tools | What they cover | | ------------------------ | ----- | ------------------------------------------------------------------------------------------- | @@ -157,5 +157,6 @@ The core tool set is 37 tools across six areas. Agents choose them for you from - Before an image or video is generated, the agent requests a credit estimate and asks you to confirm it. The server re-checks the price when the job is submitted and never charges more than the amount you approved. - Video generation needs a Plus plan or higher. Free plans have a daily image allowance and a smaller image count per request; the estimate reports these limits before you are asked to approve anything. - Reference images for editing or image-to-video are JPEG, PNG, or WebP files up to 20 MB. The agent uploads them for you, and an image it just generated can be reused as input without downloading it. +- Story Studio works on the same projects as the [web editor](https://fish.audio/app/story-studio). Importing, casting, and editing are free; only generated audio costs credits. Export requires a paid plan. - Generated audio, images, and videos are returned as permanent URLs; failed generations are refunded. - A connection is bound to the team you chose at sign-in. To work in another team, add the server again and choose that team. diff --git a/overview/mcp/tools.mdx b/overview/mcp/tools.mdx index 8d722f74..3459d134 100644 --- a/overview/mcp/tools.mdx +++ b/overview/mcp/tools.mdx @@ -1,12 +1,14 @@ --- title: "MCP Tools" sidebarTitle: "Tools" -description: "Every tool the Fish Audio MCP server exposes: voices and voice cloning, speech, transcription, file uploads, image and video generation, and Story Studio" +description: "The tools the Fish Audio MCP server exposes: voices and voice cloning, speech, transcription, file uploads, image and video generation, and Story Studio" icon: "wrench" --- This page lists the core tools that the [Fish Audio MCP server](/overview/mcp) exposes. You rarely need the names: ask for what you want in plain language and the agent picks the tools and the order to run them in. Naming a tool is still useful when you want to steer it, for example: "Estimate the video first with `estimate_video_generation`." +Your MCP client receives each tool's full schema at runtime, so argument names, accepted values, and limits come from the server — use this page to plan, not to look up parameters. Your client's tool list is authoritative and lists a few more tools than this page: the asset library tools (`list_assets`, `get_asset`, and related ones) and some internal tools are not covered here. + ## Account | Tool | What it does | @@ -32,7 +34,7 @@ This page lists the core tools that the [Fish Audio MCP server](/overview/mcp) e ## File uploads -Both tools return a temporary upload slot: the agent uploads the file, then passes the returned URL to the tool that needs it. Uploaded files are deleted automatically after 7 days. +Both tools return a temporary upload slot: the agent uploads the file, then passes the result to the tool that needs it — a URL for transcription, or a storage key for a Story Studio import. Clients that cannot make HTTP uploads (claude.ai, ChatGPT web chat) get a link the user can open to upload from their browser. Uploaded files are deleted automatically after 7 days. | Tool | What it does | | --------------------- | -------------------------------------------------------------------------------------------------- | @@ -66,20 +68,22 @@ A finished result includes a link to the item in your Fish Audio history, where ## Story Studio -Story Studio is the long-form, multi-speaker side of Fish Audio: a project holds chapters, and a chapter holds blocks, one per line of narration or dialogue, each with its own voice. These tools drive the same projects as the [Story Studio editor](https://fish.audio/app/story-studio), so an edit the agent makes appears in an open editor as it works. +Story Studio is the long-form, multi-speaker side of Fish Audio: a project holds chapters, and a chapter holds blocks — one per paragraph or heading, each with its own voice. These tools drive the same projects as the [Story Studio editor](https://fish.audio/app/story-studio), so an edit the agent makes appears in an open editor as it works. + +Blocks and chapters are addressed by short anchors returned from an earlier read, and each block carries a revision (`rev`) that a write must quote when it changes a block's text, voice, or audio settings, so two edits cannot silently overwrite each other. A block whose text or voice has changed since its audio was generated is _dirty_; only dirty blocks are regenerated, and only those are billed. -Blocks and chapters are addressed by short anchors returned from an earlier read, and each block carries a revision (`rev`) that a write must quote when it changes text or voice, so two edits cannot silently overwrite each other. A block whose text or voice has changed since its audio was generated is _dirty_; only dirty blocks are regenerated, and only those are billed. +A typical run is: find or create the project (`studio_list_projects`, `studio_create_project`, or `studio_import_document`), wait for it to settle with `studio_project`, read what is there (`studio_read_blocks`, `studio_find`), edit (`studio_write_blocks`, `studio_recast_speaker`, `studio_enhance_text`), quote and generate audio (`studio_generate`), then export (`studio_export`). `studio_help` restates this in the agent's own context, and most tools suggest calling it before your first Studio operation. ### Projects -| Tool | What it does | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `studio_help` | The operating manual for Story Studio, by topic: `quickstart`, `editing`, `tags`, `billing`, `errors`, and `workflows`. Worth calling before the first Studio operation. | -| `studio_list_projects` | Your Story Studio projects, newest first, with each one's chapter count and whether an import is still running. | -| `studio_project` | One project: the chapter outline with durations and dirty counts, the speaker roster, and the live state of an import or export. This is the tool to poll for both. | -| `studio_create_project` | Creates a project from the chapters and blocks you pass in, up to 200 blocks. A roster maps speaker names to voice IDs, so a block can name a character rather than a voice. Free. | -| `studio_import_document` | Imports a document or long text — novel, script, or article, up to 1.5M characters — into a new project. A background model splits it into chapters, casts a voice per speaker, and either adds delivery tags or rewrites for naturalness. Returns immediately; poll `studio_project`, and expect the project to be locked for writes until it finishes. Free. | -| `studio_update_project` | Project-wide settings: name, description, the default voice and backend for new blocks, audio defaults, a room-ambience scene preset, and chapter order. Defaults affect only blocks created afterwards. | +| Tool | What it does | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `studio_help` | The operating manual for Story Studio, by topic: `quickstart`, `editing`, `tags`, `billing`, `errors`, and `workflows`. Worth calling before the first Studio operation. | +| `studio_list_projects` | Your Story Studio projects, newest first, with each one's chapter count and whether an import is still running. | +| `studio_project` | One project: the chapter outline with durations and dirty counts, the speaker roster, and the live state of an import or export. This is the tool to poll for both. | +| `studio_create_project` | Creates a project from the chapters and blocks you pass in, up to 200 blocks. A roster maps speaker names to voice IDs from `search_voices`, so a block can name a character rather than a voice. Free, but not idempotent — check `studio_list_projects` before retrying a call that timed out. | +| `studio_import_document` | Imports a document or long text — novel, script, or article, up to 1.5M characters — into a new project. A background model splits it into chapters, casts a voice per speaker, and either adds delivery tags or rewrites for naturalness. Returns immediately; poll `studio_project`, and expect the project to be locked for writes until it finishes. Free, but a retry after a timeout can duplicate the import — check `studio_list_projects` first. | +| `studio_update_project` | Project-wide settings: name, description, the default voice and backend for new blocks, audio defaults, a room-ambience scene preset, and chapter order. Defaults affect only blocks created afterwards. | ### Reading and editing @@ -95,15 +99,9 @@ Blocks and chapters are addressed by short anchors returned from an earlier read ### Generating and exporting -| Tool | What it does | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `studio_generate` | Synthesizes audio for blocks, a chapter, or the whole project. By default only dirty blocks run, since unchanged audio is reused at no cost. Quote it with `dry_run=true` first: 1 credit per UTF-8 byte of spoken text, doubled for another team's professional clone voice. Runs for up to about 45 seconds; remaining blocks continue in the background and a later call collects them. | -| `studio_list_takes` | A block's previous takes, with the exact text and voice each was generated from and whether it still matches the block's current text and voice. | -| `studio_adopt_take` | Rebinds an earlier take's audio to its block — free, no generation. Only takes that still match the block's text and voice adopt cleanly. | -| `studio_export` | Exports the project, or selected chapters, to a downloadable MP3 or WAV, optionally with subtitles. Two steps: the first call returns a quote, and a second call that confirms those credits starts the background job. Only blocks that were not yet generated are billed. Requires a paid plan. | - - - In Story Studio, editing is free and only generated audio is billed: 1 credit - per UTF-8 byte of spoken text, doubled for another team's professional clone - voice. Export requires a paid plan. - +| Tool | What it does | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `studio_generate` | Synthesizes audio for blocks, a chapter, or the whole project. By default only dirty blocks run, since unchanged audio is reused at no cost. Quote it with `dry_run=true` first: 1 credit per UTF-8 byte of spoken text, doubled for another team's professional clone voice. Runs for up to about 45 seconds; remaining blocks continue in the background and `studio_project` reports what is left, so call it, then generate again to collect. | +| `studio_list_takes` | A block's previous takes, with the exact text and voice each was generated from and whether it still matches the block's current text and voice. | +| `studio_adopt_take` | Rebinds an earlier take's audio to its block — free, no generation. Only takes that still match the block's text and voice adopt cleanly. | +| `studio_export` | Exports the project, or selected chapters, to a downloadable MP3 or WAV, optionally with subtitles. Two steps: the first call returns a quote, and a second call that confirms those credits starts the background job. Only blocks that were not yet generated are billed. Requires a paid plan (any plan other than Free). | From b4a0e26a5542a65b1e4fa42cbf280a8f613f71a7 Mon Sep 17 00:00:00 2001 From: Raghav Ahuja Date: Fri, 16 Oct 2026 02:02:47 -0700 Subject: [PATCH 4/4] docs(mcp): replace em-dashes in the MCP tools page Rewrite the nine em-dashes in the new tools reference with the punctuation the rest of the page and the surrounding docs already use: commas for appositives, a period to split a sentence, and parentheses for one aside. Co-Authored-By: Claude Code --- overview/mcp/tools.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/overview/mcp/tools.mdx b/overview/mcp/tools.mdx index 3459d134..e5c18758 100644 --- a/overview/mcp/tools.mdx +++ b/overview/mcp/tools.mdx @@ -7,7 +7,7 @@ icon: "wrench" This page lists the core tools that the [Fish Audio MCP server](/overview/mcp) exposes. You rarely need the names: ask for what you want in plain language and the agent picks the tools and the order to run them in. Naming a tool is still useful when you want to steer it, for example: "Estimate the video first with `estimate_video_generation`." -Your MCP client receives each tool's full schema at runtime, so argument names, accepted values, and limits come from the server — use this page to plan, not to look up parameters. Your client's tool list is authoritative and lists a few more tools than this page: the asset library tools (`list_assets`, `get_asset`, and related ones) and some internal tools are not covered here. +Your MCP client receives each tool's full schema at runtime, so argument names, accepted values, and limits come from the server. Use this page to plan, not to look up parameters. Your client's tool list is authoritative and lists a few more tools than this page: the asset library tools (`list_assets`, `get_asset`, and related ones) and some internal tools are not covered here. ## Account @@ -34,7 +34,7 @@ Your MCP client receives each tool's full schema at runtime, so argument names, ## File uploads -Both tools return a temporary upload slot: the agent uploads the file, then passes the result to the tool that needs it — a URL for transcription, or a storage key for a Story Studio import. Clients that cannot make HTTP uploads (claude.ai, ChatGPT web chat) get a link the user can open to upload from their browser. Uploaded files are deleted automatically after 7 days. +Both tools return a temporary upload slot: the agent uploads the file, then passes the result to the tool that needs it, either a URL for transcription or a storage key for a Story Studio import. Clients that cannot make HTTP uploads (claude.ai, ChatGPT web chat) get a link the user can open to upload from their browser. Uploaded files are deleted automatically after 7 days. | Tool | What it does | | --------------------- | -------------------------------------------------------------------------------------------------- | @@ -68,7 +68,7 @@ A finished result includes a link to the item in your Fish Audio history, where ## Story Studio -Story Studio is the long-form, multi-speaker side of Fish Audio: a project holds chapters, and a chapter holds blocks — one per paragraph or heading, each with its own voice. These tools drive the same projects as the [Story Studio editor](https://fish.audio/app/story-studio), so an edit the agent makes appears in an open editor as it works. +Story Studio is the long-form, multi-speaker side of Fish Audio: a project holds chapters, and a chapter holds blocks, one per paragraph or heading, each with its own voice. These tools drive the same projects as the [Story Studio editor](https://fish.audio/app/story-studio), so an edit the agent makes appears in an open editor as it works. Blocks and chapters are addressed by short anchors returned from an earlier read, and each block carries a revision (`rev`) that a write must quote when it changes a block's text, voice, or audio settings, so two edits cannot silently overwrite each other. A block whose text or voice has changed since its audio was generated is _dirty_; only dirty blocks are regenerated, and only those are billed. @@ -81,8 +81,8 @@ A typical run is: find or create the project (`studio_list_projects`, `studio_cr | `studio_help` | The operating manual for Story Studio, by topic: `quickstart`, `editing`, `tags`, `billing`, `errors`, and `workflows`. Worth calling before the first Studio operation. | | `studio_list_projects` | Your Story Studio projects, newest first, with each one's chapter count and whether an import is still running. | | `studio_project` | One project: the chapter outline with durations and dirty counts, the speaker roster, and the live state of an import or export. This is the tool to poll for both. | -| `studio_create_project` | Creates a project from the chapters and blocks you pass in, up to 200 blocks. A roster maps speaker names to voice IDs from `search_voices`, so a block can name a character rather than a voice. Free, but not idempotent — check `studio_list_projects` before retrying a call that timed out. | -| `studio_import_document` | Imports a document or long text — novel, script, or article, up to 1.5M characters — into a new project. A background model splits it into chapters, casts a voice per speaker, and either adds delivery tags or rewrites for naturalness. Returns immediately; poll `studio_project`, and expect the project to be locked for writes until it finishes. Free, but a retry after a timeout can duplicate the import — check `studio_list_projects` first. | +| `studio_create_project` | Creates a project from the chapters and blocks you pass in, up to 200 blocks. A roster maps speaker names to voice IDs from `search_voices`, so a block can name a character rather than a voice. Free, but not idempotent, so check `studio_list_projects` before retrying a call that timed out. | +| `studio_import_document` | Imports a document or long text (novel, script, or article, up to 1.5M characters) into a new project. A background model splits it into chapters, casts a voice per speaker, and either adds delivery tags or rewrites for naturalness. Returns immediately; poll `studio_project`, and expect the project to be locked for writes until it finishes. Free, but a retry after a timeout can duplicate the import, so check `studio_list_projects` first. | | `studio_update_project` | Project-wide settings: name, description, the default voice and backend for new blocks, audio defaults, a room-ambience scene preset, and chapter order. Defaults affect only blocks created afterwards. | ### Reading and editing @@ -90,7 +90,7 @@ A typical run is: find or create the project (`studio_list_projects`, `studio_cr | Tool | What it does | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `studio_read_blocks` | Reads a whole chapter or a list of blocks: anchor, revision, voice, text, kind, dirty flag, and duration. `format=script` renders a read-only script view for showing a reader. | -| `studio_find` | Searches block text across a project, as a substring or a regular expression, and returns matching anchors with snippets — the way to fix something everywhere without reading every chapter. | +| `studio_find` | Searches block text across a project, as a substring or a regular expression, and returns matching anchors with snippets, the way to fix something everywhere without reading every chapter. | | `studio_write_blocks` | Applies up to 100 edits in order: update, insert, move, or delete blocks, with updates quoting the block's revision. Per-edit results report `ok`, `noop`, `conflict`, or `missing`, and a conflict returns the current text and revision to retry against. Free, and `dry_run` validates without writing. | | `studio_create_chapter` | Adds a chapter, optionally after an existing chapter. New chapters start with one empty block. | | `studio_update_chapter` | Renames a chapter. | @@ -103,5 +103,5 @@ A typical run is: find or create the project (`studio_list_projects`, `studio_cr | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `studio_generate` | Synthesizes audio for blocks, a chapter, or the whole project. By default only dirty blocks run, since unchanged audio is reused at no cost. Quote it with `dry_run=true` first: 1 credit per UTF-8 byte of spoken text, doubled for another team's professional clone voice. Runs for up to about 45 seconds; remaining blocks continue in the background and `studio_project` reports what is left, so call it, then generate again to collect. | | `studio_list_takes` | A block's previous takes, with the exact text and voice each was generated from and whether it still matches the block's current text and voice. | -| `studio_adopt_take` | Rebinds an earlier take's audio to its block — free, no generation. Only takes that still match the block's text and voice adopt cleanly. | +| `studio_adopt_take` | Rebinds an earlier take's audio to its block. Free, and no generation runs. Only takes that still match the block's text and voice adopt cleanly. | | `studio_export` | Exports the project, or selected chapters, to a downloadable MP3 or WAV, optionally with subtitles. Two steps: the first call returns a quote, and a second call that confirms those credits starts the background job. Only blocks that were not yet generated are billed. Requires a paid plan (any plan other than Free). |