cshape · Oct 19, 2026 · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/developer-guide/resources/coding-agents.mdx b/developer-guide/resources/coding-agents.mdx
@@ -33,7 +33,7 @@

 <CodeGroup>
 ```bash All skills
 npx skills add https://docs.fish.audio
 ```

 ```bash One skill
@@ -66,7 +66,7 @@
  </Card>

  <Card title="Stream from an LLM" icon="bolt">
    "Stream an LLM's tokens to Fish Audio TTS over the WebSocket."
  </Card>

  <Card title="Raw API, any language" icon="code">
@@ -76,7 +76,7 @@
 
 ## 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, 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.
 
 <Note>
   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
@@ -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/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
@@ -1,23 +1,24 @@
 ---
 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"
+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"
 ---
 
 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, 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.
-- **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
 
 <Tabs>
  <Tab title="Claude Code">
    ```bash
    claude mcp add --transport http fish-audio https://api.fish.audio/mcp
    ```

    Run `/mcp` inside Claude Code to sign in, then ask "Generate a short greeting with a warm English voice."
@@ -35,7 +36,7 @@
    ```json
    {
      "mcpServers": {
        "fish-audio": { "url": "https://api.fish.audio/mcp" }
      }
    }
    ```
@@ -46,11 +47,10 @@
 
   <Tab title="Codex CLI">
     ```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`.
 
   </Tab>
 
@@ -121,17 +121,56 @@
     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."
   />
+
+  <PromptCard
+    title="Produce a story"
+    icon="book"
+    prompt="Import the text of chapters.md into a new Story Studio project, then quote the credits to generate the first chapter."
+  />
 </CardGroup>
 
 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 [tools reference](/overview/mcp/tools) lists what each tool does, by area:
+
+- [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
+
+<Card title="MCP tools reference" icon="wrench" href="/overview/mcp/tools">
+  The tools the server exposes, with the exact tool names and what each one
+  does.
+</Card>
+
+## 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.
-- 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.