# MCP server Scriptivox ships an official [Model Context Protocol](https://modelcontextprotocol.io) 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) ```json { "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) ```json { "mcpServers": { "scriptivox": { "command": "npx", "args": ["-y", "@scriptivox/mcp-server"], "env": { "SCRIPTIVOX_API_KEY": "sk_live_YOUR_KEY" } } } } ``` Published as [`@scriptivox/mcp-server`](https://www.npmjs.com/package/@scriptivox/mcp-server) on npm and as `sparkleofficialmain/scriptivox-mcp-server` on Docker Hub. Source: [github.com/SparkleOfficial/scriptivox-mcp-server](https://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](/keys); see [Authentication](/docs/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](/.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 ```bash 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](/docs/versioning) for how deprecations are announced.