From 4d266bf865f66b6a66230259e373e029d8120270 Mon Sep 17 00:00:00 2001 From: Raghav Ahuja Date: Thu, 15 Oct 2026 17:32:25 -0700 Subject: [PATCH 1/6] 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/6] 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/6] 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/6] 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). | From eba2d09d02dc65ba389337b832b8001a9b609d64 Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Mon, 19 Oct 2026 13:16:12 -0700 Subject: [PATCH 5/6] docs(mcp): make the MCP tools reference accurate and release-proof Checked every claim against platform-api origin/main and the live MCP server. - Document every agent-visible tool, adding the asset library and submit_feedback, and drop the hard-coded tool counts. - Describe what each tool does for the user. Arguments, limits, and agent workflow stay in the tool definitions the client loads, so the page does not drift with each server release. - Fix claims the server contradicts: list_my_workspaces lists workspaces in the connected team, the 7-day deletion applies only to get_upload_url, and Story Studio import takes a document's text. - Move prices into a Credits section and plan rules into Good to know, so each fact lives in one place. - Add sidebarTitle "Overview" so the sidebar reads MCP Server > Overview, Tools. - Fix the Codex tab: codex mcp add needs --url for an HTTP server. - List the MCP pages in llms.txt and update the capability list on the coding agents page. --- developer-guide/resources/coding-agents.mdx | 2 +- llms.txt | 2 + overview/mcp.mdx | 60 ++++--- overview/mcp/tools.mdx | 165 ++++++++++---------- 4 files changed, 121 insertions(+), 108 deletions(-) diff --git a/developer-guide/resources/coding-agents.mdx b/developer-guide/resources/coding-agents.mdx index 01eb8681..44c8a74b 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](/overview/mcp/tools) for what the agent can call. +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, clone voices, generate speech, transcribe audio, create images and videos, and produce Story Studio projects 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/llms.txt b/llms.txt index 43c2c725..98d48939 100644 --- a/llms.txt +++ b/llms.txt @@ -7,6 +7,8 @@ - [Coding Assistant Quickstart](https://docs.fish.audio/developer-guide/resources/agent-quickstart.md): Minimal-noise entry point for AI coding assistants with retrieval order, canonical URLs, and task routing. - [Quick Start](https://docs.fish.audio/developer-guide/getting-started/quickstart.md): Generate your first AI voice with Fish Audio in under 5 minutes. - [AI Coding Assistants](https://docs.fish.audio/developer-guide/resources/coding-agents.md): Install the Fish Audio skill so your coding agent writes correct SDK and API code. +- [MCP Server](https://docs.fish.audio/overview/mcp.md): Client setup, credits, and plan requirements for connecting an MCP client to your Fish Audio account with OAuth. +- [MCP Tools](https://docs.fish.audio/overview/mcp/tools.md): What each Fish Audio MCP server tool does, grouped by area. ## API Specs diff --git a/overview/mcp.mdx b/overview/mcp.mdx index 94b16838..b93365fc 100644 --- a/overview/mcp.mdx +++ b/overview/mcp.mdx @@ -1,6 +1,7 @@ --- title: "MCP Server" -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" +sidebarTitle: "Overview" +description: "Connect Claude, Cursor, or another MCP client to your Fish Audio account for voices, speech, images, video, and Story Studio" icon: "plug" --- @@ -10,7 +11,7 @@ The Fish Audio MCP server gives AI agents direct access to your Fish Audio accou - **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. -- **Billing**: usage draws from your plan's package credits, exactly like the [web app](https://fish.audio/app). It does not consume developer API credits. Image and video generation is quoted first, and the agent asks you to confirm the price before it generates. +- **Billing**: usage is billed the same way as the [web app](https://fish.audio/app), not through the developer API. See [Credits](#credits) for what each tool costs. ## Connect @@ -46,11 +47,10 @@ The Fish Audio MCP server gives AI agents direct access to your Fish Audio accou ```bash - codex mcp add fish-audio https://api.fish.audio/mcp - codex mcp login fish-audio + codex mcp add fish-audio --url https://api.fish.audio/mcp ``` - `codex mcp login` opens the browser sign-in. Verify with `codex mcp list`. + Codex opens the browser sign-in when it adds the server. If it doesn't, run `codex mcp login fish-audio`. Verify with `codex mcp list`. @@ -125,7 +125,7 @@ Once connected, ask in plain language and the agent picks the right tools. Click @@ -133,30 +133,44 @@ 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. Your client's own tool list is what the agent actually sees, and it includes a few more tools besides these. +The [tools reference](/overview/mcp/tools) lists what each tool does, by area: -| 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 | +- [Voices](/overview/mcp/tools#voices): search the voice library and clone voices +- [Speech and transcription](/overview/mcp/tools#speech-and-transcription): text to speech and speech to text +- [File uploads](/overview/mcp/tools#file-uploads): local files for transcription, cloning, and generation +- [Images and video](/overview/mcp/tools#images-and-video): models, estimates, and generation +- [Story Studio](/overview/mcp/tools#story-studio): long-form, multi-speaker audio projects +- [Asset library](/overview/mcp/tools#asset-library): saved files, folders, and avatars +- [Account and feedback](/overview/mcp/tools#account-and-feedback): credits, workspaces, and feedback to Fish Audio The tools the server exposes, with the exact tool names and what each one does. +## Credits + +| Tool or area | Cost | +| ------------------------------------------------------- | ---------------------------------------------------------------------- | +| Speech (`text_to_speech`) | 1 credit per UTF-8 byte of text, audio tags included | +| Story Studio audio (`studio_generate`, `studio_export`) | 1 credit per UTF-8 byte of text; blocks with up-to-date audio are free | +| Transcription (`speech_to_text`) | By length of audio; `flash` costs less than `pro` | +| Images and video | The price in the estimate | + +In UTF-8, English letters, digits, and basic punctuation are one byte each, and most Chinese, Japanese, and Korean characters are three. Voice search and cloning, uploads, Story Studio import and editing, estimates and quotes, and the asset library are free. Speech and Story Studio audio in another team's [professional voice clone](/overview/platform/create-voice/professional-voice-clone) cost double, and failed generations are refunded. + ## Good to know -- Add audio tags in square brackets inside the text to control delivery: `[whispering]`, `[excited]`, `[laughing]`. Tags are performed, never spoken. +- Add [audio tags](/developer-guide/core-features/emotions) in square brackets inside the text to control delivery, such as `[whispering]`, `[excited]`, or `[laughing]`. - If no voice is specified, a curated default voice for the requested language is used. -- Local files can be transcribed too. The agent uploads them to a temporary slot that is deleted automatically after 7 days. -- 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. +- Local files for transcription or cloning go to temporary storage that is deleted after 7 days, while files you upload as inputs for image or video generation are kept in your workspace. +- The agent asks you to approve an image or video estimate before it generates; if the credit price changes before it submits, nothing is charged and the agent asks you again. +- Every account sees the same tools, and plan requirements are checked when a tool runs. +- Video (including lip sync and talking avatars) needs a Plus plan or higher, and Story Studio export needs a paid plan. +- Free plans limit how many images you can generate, and your [plan](https://fish.audio/app/billing) sets how many private or unlisted voices you can keep. +- The estimate or quote tells you when a request is over your plan, before anything is charged. +- New voice clones are unlisted by default, so anyone with the voice ID can use them; ask for a private voice to keep one to your workspace. +- Generated audio, images, and videos are returned as permanent links that anyone with the link can open. +- 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. +- Voice, speech, transcription, and Story Studio tools use your team's default workspace, while image, video, and asset library tools use the workspace you choose (`list_my_workspaces` lists them). +- Tools can change between releases; reconnect your client to refresh its tool list. diff --git a/overview/mcp/tools.mdx b/overview/mcp/tools.mdx index e5c18758..861a34a4 100644 --- a/overview/mcp/tools.mdx +++ b/overview/mcp/tools.mdx @@ -1,107 +1,104 @@ --- title: "MCP Tools" sidebarTitle: "Tools" -description: "The tools the Fish Audio MCP server exposes: voices and voice cloning, speech, transcription, file uploads, image and video generation, and Story Studio" +description: "What each tool on the Fish Audio MCP server does, grouped by area" 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`." +These are the tools the [Fish Audio MCP server](/overview/mcp) exposes. Naming one in a prompt helps when you want to steer a step, for example "List my own voices with `search_voices`." -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 | -| -------------------- | ------------------------------------------------------------------------------------------------ | -| `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. | +The agent gets each tool's arguments from the server when your client connects. Costs are in [Credits](/overview/mcp#credits), and plan requirements in [Good to know](/overview/mcp#good-to-know). ## 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. | +| Tool | What it does | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `search_voices` | Searches the public voice library, browses popular voices for a language, or lists your own workspace's voices (`self`). | +| `get_voice` | Shows one voice's description, languages, tags, popularity, and a sample. | +| `create_voice_clone` | Creates a voice from recordings of one speaker ([what makes a good sample](/features/voice-cloning)) once you confirm you have the rights to it. Free. | +| `verify_voice_clone` | Finishes a clone that needs speaker verification, from a recording of the speaker reading a short passage Fish Audio provides. | ## 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. | +Long text may come back as several clips. How much text one call can take depends on your plan, and `get_credit_balance` shows the limit. + +| Tool | What it does | +| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `text_to_speech` | Speaks text with a voice, or the default voice for the language, and returns a permanent audio link. | +| `speech_to_text` | Transcribes audio from a direct HTTPS link to the file, such as one from `get_upload_url`; `pro` is the default and accepts a language hint, and `flash` costs less. | ## File uploads -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. +In clients that cannot upload files themselves, such as claude.ai, the agent gives you a link to upload the file from your browser. Anyone with the link can upload to it until it expires, so don't share it. -| 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. | +| Tool | What it does | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `get_upload_url` | Uploads a local file to temporary storage so the agent can pass it to another tool, for example a recording to transcribe or samples to clone. | +| `create_media_upload` | Uploads an image, video, or audio file to your workspace as a generation input; `get_media_model` lists the files each model accepts. | ## 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. - +Jobs run in the background, and finished results also appear in your [image and video history](https://fish.audio/app/image-video/history/). The agent can use a result from the same workspace as the input to another generation, for example to animate an image it made or to lip-sync a video to `text_to_speech` audio, without downloading it. + +| Tool | What it does | +| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `list_media_models` | Lists the image and video models, what each can do (for example text-to-image, image edit, upscale, text-to-video, image-to-video, lip sync, or talking avatar), and their prices. | +| `get_media_model` | Shows one model's options, required inputs, and accepted files. | +| `estimate_image_generation` | Prices and checks an image request, including your plan's limits. Free. | +| `estimate_image_edit` | Prices and checks an image edit or upscale, including your plan's limits. Free. | +| `estimate_video_generation` | Prices and checks a video request, including your plan's limits. Free. | +| `generate_image` | Submits the image request you approved. | +| `generate_image_edit` | Submits the image edit or upscale you approved. | +| `generate_video` | Submits the video request you approved. | +| `get_generation_status` | Checks running jobs; finished jobs include their results. | +| `get_generation_result` | Shows the results and charges of one finished job. | ## 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. - -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. - -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 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 - -| 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 `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, 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). | +A project holds chapters, and chapters hold blocks (a paragraph or heading), each with its own voice. These tools edit the same projects as the [Story Studio editor](https://fish.audio/app/story-studio), and edits show up in an open editor. Importing and editing are free; audio [costs credits](/overview/mcp#credits), and the agent quotes it first. + +A block needs new audio when it has none or its text, voice, or settings changed. If a block is changed back to an earlier version, `studio_generate` reuses that audio for free. No tool deletes projects or chapters; delete them in the editor. + +| Tool | What it does | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `studio_help` | Shows the Story Studio manual for agents, by topic. | +| `studio_list_projects` | Lists your workspace's projects. | +| `studio_project` | Shows one project's chapters, how many blocks in each still need audio, the voices in use, and the status of an import or export. | +| `studio_create_project` | Creates a project from chapters and blocks the agent writes. | +| `studio_import_document` | Imports a document's text (a novel, script, or article) into a new project, splitting it into chapters, casting voices, and adding audio tags; the project is read-only until the import finishes. | +| `studio_update_project` | Changes the project's name, description, audio settings, room ambience, chapter order, and the default voice and model for new blocks. | +| `studio_read_blocks` | Reads a chapter or specific blocks, optionally with links to their audio, or shows a chapter as a script. | +| `studio_find` | Searches text across a project. | +| `studio_write_blocks` | Edits, inserts, moves, or deletes blocks. | +| `studio_create_chapter` | Adds a chapter. | +| `studio_update_chapter` | Renames a chapter. | +| `studio_recast_speaker` | Switches every block that uses one voice to another voice. | +| `studio_enhance_text` | Returns one block's text polished for speech, with numbers, dates, and symbols spelled out and audio tags added. | +| `studio_generate` | Generates audio for blocks, a chapter, or the whole project, only for the blocks that need it unless asked to redo one. | +| `studio_list_takes` | Lists a block's earlier audio versions (takes). | +| `studio_adopt_take` | Switches a block back to an earlier take that still matches it. Free. | +| `studio_export` | Exports the project or chapters as MP3 or WAV, optionally with subtitles. The agent quotes the credits for blocks that still need audio and starts the export after you confirm. | + +## Asset library + +Your workspace's [Asset Library](https://fish.audio/app/assets) holds saved images, audio, and video in folders, plus avatars, which pair a portrait image with an optional default voice. These tools never delete anything; delete files in the web app. + +| Tool | What it does | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| `list_assets` | Lists the files in a folder, or searches across the workspace. | +| `get_asset` | Shows one file's permanent link and a temporary download link. | +| `save_asset` | Saves a file uploaded with `create_media_upload`, or a finished image, video, or `text_to_speech` result, to the library. | +| `update_asset` | Renames or moves a file. | +| `list_asset_collections` | Lists folders and avatars. | +| `get_asset_collection` | Shows one folder or avatar, including an avatar's portrait and default voice. | +| `create_asset_folder` | Creates a folder. | +| `create_avatar` | Creates an avatar; it makes no video itself, but the agent can use the avatar's portrait to make a talking-avatar video. | +| `update_asset_collection` | Renames or moves a folder, or changes an avatar's name, portrait, or default voice. | + +## Account and feedback + +| Tool | What it does | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `get_credit_balance` | Shows the team this connection uses, its plan and remaining credits, and how much text one speech call can take. | +| `list_my_workspaces` | Lists your workspaces in the team you connected. | +| `submit_feedback` | Sends a short note about the tools to Fish Audio; agents are asked to send one when something is confusing or broken, so yours may do it without asking you. | From f47b50d2a21f8ef296d9a03acbfc1a16d0b8b75f Mon Sep 17 00:00:00 2001 From: Cale Shapera Date: Mon, 19 Oct 2026 16:09:19 -0700 Subject: [PATCH 6/6] docs(mcp): describe the upload tools as returning an upload link get_upload_url and create_media_upload return a link; the agent, or you through the browser link, then uploads the file. Raised by CodeRabbit. --- overview/mcp/tools.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/overview/mcp/tools.mdx b/overview/mcp/tools.mdx index 861a34a4..fccf2c62 100644 --- a/overview/mcp/tools.mdx +++ b/overview/mcp/tools.mdx @@ -29,12 +29,12 @@ Long text may come back as several clips. How much text one call can take depend ## File uploads -In clients that cannot upload files themselves, such as claude.ai, the agent gives you a link to upload the file from your browser. Anyone with the link can upload to it until it expires, so don't share it. +Both tools return an upload link, and the agent then uploads the file to it. In clients that cannot upload files themselves, such as claude.ai, the agent gives you a link to upload the file from your browser instead. Anyone with the link can upload to it until it expires, so don't share it. -| Tool | What it does | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| `get_upload_url` | Uploads a local file to temporary storage so the agent can pass it to another tool, for example a recording to transcribe or samples to clone. | -| `create_media_upload` | Uploads an image, video, or audio file to your workspace as a generation input; `get_media_model` lists the files each model accepts. | +| Tool | What it does | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `get_upload_url` | Creates a link for uploading a local file to temporary storage, so the agent can pass the file to another tool, for example a recording to transcribe or samples to clone. | +| `create_media_upload` | Creates a link for uploading an image, video, or audio file to your workspace as a generation input; `get_media_model` lists the files each model accepts. | ## Images and video