Developer docs

MCP server

Connect an AI app to your SoundHalo account so it can dub videos, make voice-overs and translate subtitles for you. Paid actions always show you a quote first.

What it is

MCP (Model Context Protocol) is an open standard that lets AI apps such as Claude and ChatGPT call outside tools. The SoundHalo MCP server is at:

server URL
https://api.soundhalo.com/mcp

Once connected, you can ask things like "dub this video into Spanish with a female voice" and paste a link. The app calls SoundHalo as your account, so it uses your plan minutes, balance and limits, just like the website.

OAuth or API key

The server accepts two ways to sign in:

  • OAuth sign-in: the app opens a SoundHalo page, you sign in with your SoundHalo account and approve the app on a consent screen. You never paste a key. ChatGPT and Claude.ai only support this way, which is why the server offers it. The app gets an access token that lasts one hour, plus a refresh token that lasts 30 days and gets it new access tokens.
  • API key: send Authorization: Bearer sh_live_.... This is simplest for Claude Code, scripts and your own agents, which can send a header. Create keys on the Developers page.

Both act as your account in the same way. OAuth uses the standard parts MCP clients expect: dynamic client registration (the app registers itself, so there is no client id to copy) and PKCE (a check that stops a stolen sign-in code from being used by another app).

Claude Code

With OAuth:

terminal
claude mcp add --transport http soundhalo https://api.soundhalo.com/mcp

Then run /mcp inside Claude Code, choose soundhalo and sign in in the browser window that opens.

Or with an API key:

terminal
claude mcp add --transport http soundhalo https://api.soundhalo.com/mcp \
  --header "Authorization: Bearer sh_live_..."

Claude.ai and Claude Desktop

  1. Open Settings > Connectors.
  2. Choose Add custom connector.
  3. Paste https://api.soundhalo.com/mcp and add it.
  4. Press Connect, sign in to SoundHalo and approve.

Custom connectors may not be available on every Claude plan or in every workspace; an admin may need to allow them.

ChatGPT

  1. Open Settings > Apps & Connectors and turn on developer mode.
  2. Choose Create.
  3. Name it SoundHalo, paste https://api.soundhalo.com/mcp and choose OAuth.
  4. Sign in to SoundHalo and approve.

Developer mode depends on your ChatGPT plan and workspace settings.

MCP Inspector

To try the tools by hand, run the MCP Inspector:

terminal
bunx @modelcontextprotocol/inspector

Choose the Streamable HTTP transport, enter https://api.soundhalo.com/mcp, then either sign in with OAuth or add an Authorization header with your key.

Tools

ToolWhat it doesUses
list_voicesList catalog voices and their languages. Optional language filter.Nothing
get_accountPlan, dubbing minutes left, daily allowances and the balance in micro-dollars.Nothing
import_mediaCopy a public audio or video link into SoundHalo and get an asset id and token.One daily upload
start_dubStart a dub from a link or an uploaded file. Stops at a quote.Transcription and translation allowances
get_dubStatus, quote, translated lines and the output file.Nothing
confirm_dubGenerate a quoted dub. Needs max_balance_micros the user approved.Dubbing minutes, then the balance up to the approved amount
cancel_dubCancel a dub before speech starts.Nothing more
quote_voice_overCheck a timed script and return what it would use, plus a confirmation_id.Nothing
create_voice_overMake the quoted voice-over. Needs the confirmation_id and the exact quoted script.Text to speech characters (or cloned-voice cost)
quote_subtitle_translationCount the characters of timed subtitles and return a confirmation_id.Nothing
translate_subtitlesTranslate the quoted subtitles. Needs the confirmation_id and the same lines.Translation characters and one daily file
get_jobRead an async job, such as a transcription, with its id and token.Nothing
get_download_linkTurn an output file into a plain download link that works for one hour.Nothing

Tool results are the same JSON the API returns. Amounts are in micro-dollars (1,000,000 = $1); the server tells the AI app to show them to you in dollars.

No paid action runs from a single tool call. The AI app has to show you a quote and come back with proof that you saw it:

  • Dubs: start_dub stops at a quote. confirm_dub needs max_balance_micros, the amount you approved. It must be at least the quoted balance amount, and SoundHalo never takes more. This is the same protection as the dubbing API.
  • Voice-overs and subtitle translations: the quote tool returns a confirmation_id. The create tool only runs with that id, for exactly the script (or lines), voice and format that were quoted. Each id works once and lasts 15 minutes. If anything changed, the tool refuses with CONFIRMATION_REQUIRED and the app must quote again.

Voice-overs and subtitle translations use daily plan allowances, never the balance. Only dubs (past your plan minutes) can use the balance.

The confirmation rules make sure a quote exists and matches. They cannot prove that a person, not the AI, said yes. Read quotes before you approve them, and keep your balance at an amount you are comfortable with.

Disconnect an app

The Developers page lists connected apps. Disconnect removes an app's access. If you connected with an API key, revoke the key instead.

Technical details

  • Transport: Streamable HTTP. The server is stateless: every POST carries one JSON-RPC message (or a batch of up to 20) and gets a JSON answer. There is no SSE stream and no session; GET /mcp returns 405.
  • Without valid sign-in, /mcp returns 401 with a WWW-Authenticate header that points clients to /.well-known/oauth-protected-resource/mcp, where OAuth discovery starts.
  • Tools call the public API inside SoundHalo, so every limit, error message and allowance is the same as the HTTP API.