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.
The documentation server
Beyond the product server above, https://www.scriptivox.com/mcp/docs speaks the same Streamable HTTP protocol and registers exactly two tools:
| Tool | What it does |
|---|---|
search_docs | Lexical search across these documentation pages and the agent guides. Returns URLs and summaries, best match first. |
get_doc | Fetches one page as markdown, by slug (quickstart, authentication, ...). |
Both need no credential, touch no account, and cannot change anything. They are registered on the main /mcp endpoint too, so a client already connected there does not have to open a second transport to look something up. The separate endpoint exists for a client that wants reference material and nothing else, and does not want to be handed thirty-nine tools it will never call.
The scoping is a clear contract, not a permission boundary — do not build anything that treats /mcp/docs as a sandbox.
Tools in the page itself (WebMCP)
The two servers above serve an agent calling Scriptivox from outside. WebMCP is the other case: an agent driving the browser a person is already signed into. It needs no credential at all, because the session is right there.
Scriptivox registers its page tools with document.modelContext.registerTool() (navigator.modelContext is the deprecated pre-Chrome-150 alias, and is still accepted as a fallback):
| Tool | What it does |
|---|---|
scriptivox_whoami | Whether anybody is signed in on this page, and as whom. Call it first. |
scriptivox_open_signup | Opens the signup form. It does not create an account. |
scriptivox_get_plan_status | The signed-in person's plan and entitlements. |
scriptivox_start_plan_checkout | Returns a Stripe Checkout URL. Charges nothing. |
scriptivox_create_api_key | Mints an API key — the bridge from a web account to the metered API. |
There is deliberately no transcription tool here. Web plans include unlimited transcription and are priced for one human; an agent driving the browser could otherwise run an archive through a plan sold on the assumption that a person is clicking. Programmatic transcription belongs on the metered API, and scriptivox_create_api_key is the door to it.
scriptivox_open_signup navigates to the form and cannot submit it, which is the same reason the homepage's declarative toolname attributes are on the question form and not on the signup form.
The homepage also carries a WebMCP-annotated <form> (toolname="ask_scriptivox") that works with no JavaScript at all — it GETs /ask, the NLWeb endpoint, which renders HTML when the client prefers it and JSON otherwise.
Availability: WebMCP is a W3C draft. It is a secure-context feature and absent in most browsers today; the page registers what it can and does nothing when the API is missing.
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.