MCP server
Scriptivox ships an official Model Context Protocol server, so Claude, ChatGPT and any other MCP client can transcribe audio and video as a native tool call instead of you writing an API integration.
There are two ways to run it. They expose the same tools and differ only in where the code runs.
| Hosted | Local (stdio) | |
|---|---|---|
| Transport | Streamable HTTP | stdio |
| Where | https://platform.scriptivox.com/mcp | npx @scriptivox/mcp-server |
| Install | Nothing to install | Node 18+ |
| Local files | No — this server cannot read your disk | Yes, transcribe_upload works |
| Best for | Web clients, quick setup, shared configs | Desktop clients with local media |
Hosted (Streamable HTTP)
{"mcpServers": {"scriptivox": {"url": "https://platform.scriptivox.com/mcp","headers": {"Authorization": "Bearer sk_live_YOUR_KEY"}}}}
https://www.scriptivox.com/mcp resolves to the same endpoint; platform. is canonical.
The endpoint is stateless: it issues no Mcp-Session-Id and every request stands alone, so it behaves identically whether or not the instance handling it saw your initialize. It always answers with a single JSON response rather than an SSE stream, which the protocol permits and every conforming client handles.
Protocol revisions accepted: 2025-11-25, 2025-06-18, 2025-03-26. initialize echoes yours when we speak it, and otherwise answers with the newest we support so a client that is one revision ahead can step down rather than fail.
Local (stdio)
{"mcpServers": {"scriptivox": {"command": "npx","args": ["-y", "@scriptivox/mcp-server"],"env": { "SCRIPTIVOX_API_KEY": "sk_live_YOUR_KEY" }}}}
Published as @scriptivox/mcp-server on npm and as sparkleofficialmain/scriptivox-mcp-server on Docker Hub. Source: github.com/SparkleOfficial/scriptivox-mcp-server.
Use this one when the media is on the machine running the client — it is the only version with filesystem access, and therefore the only one where transcribe_upload can work.
Authentication
Get a key at /keys; see Authentication for the details.
The hosted endpoint accepts Authorization: Bearer sk_live_…, bare Authorization: sk_live_…, or X-Api-Key: sk_live_…. Cookies are ignored entirely. Your key is used for exactly one upstream API call per tool invocation and is never logged or stored.
Four tools work with no key at all
get_pricing, get_supported_languages, get_product_info and get_api_docs need no credential, so an agent can find out what Scriptivox costs and what it covers before anyone has created an account.
Calling a key-requiring tool without a key does not return HTTP 401 — it returns a normal tool result with isError: true and instructions. That is deliberate: a 401 from an MCP endpoint sends clients into OAuth discovery, and there is no authorization server behind it, so you would get a dead end instead of the one sentence you need.
Tools
| Tool | Key? | What it does |
|---|---|---|
get_pricing | no | API rates and plan information. |
get_supported_languages | no | The 119 languages and their codes. |
get_product_info | no | What Scriptivox does, by topic. |
get_api_docs | no | Pointers into this documentation. |
check_balance | yes | Remaining balance and estimated audio hours. |
transcribe_url | yes | Transcribe from a public URL. |
transcribe_status | yes | Poll a job and fetch its transcript. |
transcribe_upload | yes | Transcribe a local file. Local server only. |
transcribe_cancel | yes | Stop an in-flight job, release its reservation. |
transcribe_delete | yes | Soft-delete a finished transcription. |
list_transcriptions | yes | List jobs with filters and cursor pagination. |
export_transcript | yes | Export as SRT, WebVTT or plain text. |
transcription_url and transcription_status are also registered as deprecated aliases of transcribe_url and transcribe_status, kept so @scriptivox/mcp-server@1.0.x configurations keep working. They are removed in 2.0.0.
The authoritative list is the manifest at /.well-known/mcp, and a build check asserts that it, the hosted endpoint and the published stdio server all register exactly the same names — a client that reads a tool out of the manifest must never get "unknown tool" back when it calls it.
Two things to expect
transcribe_url waits, but not forever. By default it polls until the job finishes. The hosted endpoint stops waiting after about 55 seconds and returns a non-error result carrying the transcription_id and telling you to call transcribe_status — the job itself is unaffected and still running. Pass await_completed: false to get the id immediately instead, or a webhook_url to be told rather than having to ask. The local stdio server has no such ceiling and waits up to 10 minutes.
transcribe_upload cannot work over the hosted endpoint. It takes a path on your filesystem, and this server has none of your files. It is still registered — hiding a tool the manifest lists would be its own bug — and returns an error explaining the three ways forward: a public URL with transcribe_url, the local stdio server, or the three-step REST upload flow.
Checking it by hand
curl -s https://platform.scriptivox.com/mcp \-H 'Content-Type: application/json' \-H 'Accept: application/json, text/event-stream' \-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'curl -s https://platform.scriptivox.com/mcp \-H 'Content-Type: application/json' \-H 'MCP-Protocol-Version: 2025-11-25' \-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
GET and DELETE answer 405 — there is no standalone stream to open and no session to terminate.
Versioning
The MCP server follows semver independently of the API's /v1 path: a tool renamed in the server is a breaking change to the npm package, not to the REST API. See Versioning for how deprecations are announced.