Skip to content

Document the product MCP server, drop the docs-MCP hooks #105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leng-yue merged 1 commit into from
Jul 22, 2026
Merged

Document the product MCP server, drop the docs-MCP hooks #105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion developer-guide/resources/agent-quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
<Steps>
<Step title="Install the skill">
```bash
npx skills add https://docs.fish.audio

Check warning on line 12 in developer-guide/resources/agent-quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

developer-guide/resources/agent-quickstart.mdx#L12 

Did you really mean 'npx'?
```

This installs both Fish Audio skills (a canonical copy in `.agents/skills/`, with symlinks for Claude Code and Cursor). Run `npx skills update` later to refresh them.
Expand Down Expand Up @@ -56,7 +56,7 @@

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

Check warning on line 59 in developer-guide/resources/agent-quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

developer-guide/resources/agent-quickstart.mdx#L59 

Did you really mean 'npx'?
```

```bash One skill
Expand All @@ -74,7 +74,7 @@
</CodeGroup>

<Card title="AI Coding Agents — full guide" icon="robot" href="/developer-guide/resources/coding-agents" horizontal>
Targeting specific agents, the live-docs MCP server, skill-vs-MCP, and reading the skills before you install.
Targeting specific agents, the Fish Audio MCP server, and reading the skills before you install.
</Card>

## Next steps
Expand Down Expand Up @@ -164,7 +164,7 @@
- **Generate speech** → Quick Start, the Text to Speech guide, and `POST /v1/tts`.
- **Transcribe audio** → the Speech to Text guide and `POST /v1/asr`.
- **Clone or manage voices** → Creating Voice Models and the `/model` endpoints.
- **Stream audio in real time** → AsyncAPI, WebSocket TTS Streaming, and the realtime guides.

Check warning on line 167 in developer-guide/resources/agent-quickstart.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

developer-guide/resources/agent-quickstart.mdx#L167 

Did you really mean 'realtime'?
- **Pick a model or estimate cost** → Models Overview and Pricing & Rate Limits.
</Accordion>

Expand Down
48 changes: 2 additions & 46 deletions developer-guide/resources/coding-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@

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

Check warning on line 36 in developer-guide/resources/coding-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

developer-guide/resources/coding-agents.mdx#L36 

Did you really mean 'npx'?
```

```bash One skill
Expand Down Expand Up @@ -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."

Check warning on line 69 in developer-guide/resources/coding-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

developer-guide/resources/coding-agents.mdx#L69 

Did you really mean 'LLM's'?
</Card>

<Card title="Raw API, any language" icon="code">
Expand All @@ -76,54 +76,10 @@

## Or connect via MCP

Prefer live documentation search inside your editor over a self-contained skill file? Connect the Fish Audio MCP server, which serves the latest docs to your agent.

<Tabs>
<Tab title="Claude Code">
```bash
claude mcp add --transport http fish-audio --scope project https://docs.fish.audio/mcp
```

This writes a `.mcp.json` in your project root. Verify with `claude mcp list` (you should see `fish-audio`), then ask "What Fish Audio TTS models are available?"

<Accordion title="Installation scopes">
- **`--scope project`** (recommended): config in `.mcp.json`, version-controlled and shared with your team.
- **`--scope user`**: global across your projects, private to your account.
- **`--scope local`** (default): project-specific and private to you.
</Accordion>
</Tab>

<Tab title="Cursor">
Open the command palette (`Cmd/Ctrl+Shift+P`) → "Open MCP settings" → "Add custom MCP", and add:

```json
{
"mcpServers": {
"fish-audio": { "url": "https://docs.fish.audio/mcp" }
}
}
```

Save and reload Cursor, then ask "What Fish Audio TTS models are available?"
</Tab>

<Tab title="Windsurf">
Go to `Settings → Cascade → MCP Servers → View raw config` (`~/.codeium/windsurf/mcp_config.json`) and add:

```json
{
"mcpServers": {
"fish-audio": { "url": "https://docs.fish.audio/mcp" }
}
}
```

Save, refresh, then in Cascade ask "Search Fish Audio docs for TTS API usage."
</Tab>
</Tabs>
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.

<Note>
**Skill vs MCP:** the skill is a self-contained instruction file that works offline after install; MCP fetches the latest docs live. You can use both. 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.
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.

@coderabbitai coderabbitai Bot Jul 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use relative paths for the internal documentation links.

These links point to the same docs site, so replace the absolute URLs with root-relative paths.

Suggested fix 
-  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.
+  This site also exposes [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt) for agents that fetch docs directly.

As per coding guidelines: “Use relative paths for internal links” and “Do not use absolute URLs for internal links.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
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.
This site also exposes [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt) for agents that fetch docs directly.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@developer-guide/resources/coding-agents.mdx` at line 82, Update the llms.txt
and llms-full.txt links in the documentation text to use root-relative paths
instead of absolute docs.fish.audio URLs, preserving the existing link labels
and destinations.

Source: Coding guidelines

</Note>

## Next steps
Expand Down
8 changes: 3 additions & 5 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@
{
"group": "Platform (Web App)",
"pages": [
"overview/platform"
"overview/platform",
"overview/mcp"
]
},
{
Expand Down Expand Up @@ -273,10 +274,7 @@
"view",
"chatgpt",
"claude",
"perplexity",
"mcp",
"cursor",
"vscode"
"perplexity"
]
},
"fonts": {
Expand Down
98 changes: 98 additions & 0 deletions overview/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
title: "MCP Server"
description: "Connect Claude, Cursor, or any MCP client to your Fish Audio account — search voices, generate speech, and transcribe audio"
icon: "plug"
---

The Fish Audio MCP server gives AI agents direct access to your Fish Audio account: they can browse the voice library, generate speech, and transcribe audio for you.

- **Endpoint**: `https://api.fish.audio/mcp` (streamable HTTP)

Check warning on line 9 in overview/mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

overview/mcp.mdx#L9 

Did you really mean 'streamable'?
- **Authentication**: OAuth. Your MCP client opens a browser window and you sign in with your Fish Audio account — no API key required.
- **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.

## Connect

<Tabs>
Comment on lines +13 to +15

@coderabbitai coderabbitai Bot Jul 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add prerequisites before the connection tabs.

This procedural section should first state requirements such as a Fish Audio account, an MCP client supporting streamable HTTP/OAuth, and browser access for sign-in.

Suggested addition 
+Before you begin:
+
+- Make sure you have a Fish Audio account.
+- Use an MCP client that supports streamable HTTP and OAuth.
+- Make sure the client can open a browser for sign-in.
+
 ## Connect

As per coding guidelines: “Include prerequisites at the start of procedural content.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## Connect
<Tabs>
Before you begin:
- Make sure you have a Fish Audio account.
- Use an MCP client that supports streamable HTTP and OAuth.
- Make sure the client can open a browser for sign-in.
## Connect
<Tabs>
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@overview/mcp.mdx` around lines 13 - 15, Update the Connect section in the MCP
documentation before the Tabs component to add a concise prerequisites statement
covering a Fish Audio account, an MCP client that supports streamable
HTTP/OAuth, and browser access for sign-in. Keep the existing connection tabs
and procedural steps unchanged.

Source: Coding guidelines

<Tab title="Claude Code">
```bash
claude mcp add --transport http fish-audio https://api.fish.audio/mcp

Check warning on line 18 in overview/mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

overview/mcp.mdx#L18 

Did you really mean 'claude'?

Check warning on line 18 in overview/mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

overview/mcp.mdx#L18 

Did you really mean 'mcp'?
```

Run `/mcp` inside Claude Code to sign in, then ask "Generate a short greeting with a warm English voice."

</Tab>

<Tab title="Claude.ai">
Go to **Settings → Connectors → Add custom connector** and enter
`https://api.fish.audio/mcp`. Claude walks you through the sign-in.
</Tab>

<Tab title="Cursor">
Open the command palette (`Cmd/Ctrl+Shift+P`) → "Open MCP settings" → "Add custom MCP", and add:

```json
{
"mcpServers": {
"fish-audio": { "url": "https://api.fish.audio/mcp" }

Check warning on line 36 in overview/mcp.mdx

View check run for this annotation

Mintlify / Mintlify Validation (hanabiaiinc) - vale-spellcheck

overview/mcp.mdx#L36 

Did you really mean 'mcp'?
}
}
```

Cursor prompts you to sign in on first use.

</Tab>

<Tab title="Codex CLI">
```bash
codex mcp add fish-audio https://api.fish.audio/mcp
codex mcp login fish-audio
```

`codex mcp login` opens the browser sign-in. Verify with `codex mcp list`.

</Tab>

<Tab title="Windsurf">
Go to `Settings → Cascade → MCP Servers → View raw config` (`~/.codeium/windsurf/mcp_config.json`) and add:

```json
{
"mcpServers": {
"fish-audio": { "url": "https://api.fish.audio/mcp" }
}
}
```

</Tab>
</Tabs>

## Try it

Once connected, ask in plain language — the agent picks the right tools:

<CardGroup cols={2}>
<Card title="Narrate a script" icon="microphone">
"Find a calm English narration voice and read intro.md aloud — give me the audio link."
</Card>

<Card title="Voice casting" icon="magnifying-glass">
"Show me the three most popular Japanese voices and play their samples."
</Card>

<Card title="Transcribe a recording" icon="waveform">
"Transcribe meeting.mp3 and summarize the action items." (the agent uploads the file, then transcribes it)
</Card>

<Card title="Check spend" icon="wallet">
"How many Fish Audio credits do I have left?"
</Card>
</CardGroup>

In coding agents like Claude Code and Codex, tools compose with the shell: the agent can download the generated audio URL with `curl`, upload local recordings for transcription, or batch-generate a directory of scripts.

## Good to know

- Add audio tags in square brackets inside the text to control delivery — `[whispering]`, `[excited]`, `[laughing]`. Tags are performed, never spoken.
- If no voice is specified, a curated default voice for the requested language is used.
- Generated audio is returned as a permanent URL; failed generations are refunded.
- Local files can be transcribed too — the agent uploads them to a temporary slot that is deleted automatically after 7 days.
Loading