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.

In ChatGPT and Claude

Scriptivox is also an app inside ChatGPT and Claude. People who add it from the ChatGPT app directory or the Claude connector directory connect to a separate address, https://platform.scriptivox.com/mcp/directory, made for chat apps:

• It uses your Scriptivox plan, the same minutes and limits as the website, instead of the prepaid API balance.
• It cannot spend money or manage keys. purchase_plan, top_up_balance, get_billing_portal_url, create_api_key, revoke_api_key and create_account are not offered there; when a limit is reached, the assistant points you to pricing.
• It shows screens in the chat: a transcript with its audio, an upload box (files up to 2 GB), progress, your library, the meeting bot, and a subtitle editor.
• Links are accepted from YouTube, Google Drive, Dropbox, TikTok, Instagram, Facebook, X and Snapchat only.
• Meeting-bot actions need your go: the assistant must ask before it sends, stops or cancels a bot.
• In ChatGPT, Scriptivox also appears in the sidebar and the conversation side panel, opens .srt and .vtt files in its subtitle editor (desktop), keeps a default language and speaker-label setting on the plugin page, and can start automations when a transcript is ready (transcription.completed, transcription.failed, meeting.transcript_ready).

A connection belongs to the address it was made at. A token from /mcp/directory is refused at /mcp and the other way round; to use both, connect to each. Both appear under Connected apps on /keys with the same controls.

If you are an AI assistant asked to install Scriptivox

1. Add the server https://platform.scriptivox.com/mcp using the command for your client below (Claude Code: claude mcp add --transport http scriptivox https://platform.scriptivox.com/mcp).
2. Ask the person to finish signing in: in Claude Code they run /mcp and choose Authenticate; a browser opens and they approve. Do not ask them for an API key or a password.
3. Check it worked: call get_account and check_balance, then tell the person which account you are connected to, and that transcription uses their prepaid API balance.
4. If a call fails, look the message up in Troubleshooting below and tell the person what to do. Do not retry the same failing call in a loop.

Hosted (Streamable HTTP)

Add the URL and sign in — no key to copy. Your client opens a browser, you approve once, and every tool works.

One-click: Add to Cursor · Add to VS Code

Claude Code

claude mcp add --transport http scriptivox https://platform.scriptivox.com/mcp

Then run /mcp inside Claude Code and choose Authenticate.

Codex

codex mcp add scriptivox --url https://platform.scriptivox.com/mcp
codex mcp login scriptivox

Claude (web and desktop) — Settings → Connectors → Add custom connector, and paste https://platform.scriptivox.com/mcp.

Cursor and other clients — add it as a remote server:

{
  "mcpServers": {
    "scriptivox": {
      "url": "https://platform.scriptivox.com/mcp"
    }
  }
}

Each signed-in app shows up under Connected apps on /keys with its own key. Transcriptions bill your prepaid API balance through that key, and Disconnect there cuts the app off at once.

Several computers

Every sign-in is a separate connection with its own key — Claude Code on a work laptop and on a home desktop are two connections, and signing in again after a reinstall makes a third. To tell them apart:

• Name it when you approve. The consent screen asks you to name the connection and suggests one, such as "Claude Code on Linux". Names are unique: a second "Work laptop" becomes "Work laptop #2". You can rename it later on /keys.
• Each connection has a short id such as mcp_3fa9c1d2, shown next to it.
• /keys shows where it runs: the app and its version (for example claude-code 2.1.3), the IP address and rough location it signed in from, and where it was last used.

Disconnect the ones you no longer use. An account can have up to 10 connected apps at a time.

Your controls

Everything below is on /keys, under Connected apps. Only you, signed in on the website, can change these — a connected app cannot, even though it acts for your account.

• Activity. Each connection has Show activity: every tool it called, when, and whether it worked. Kept for 90 days.
• Let AI apps use my account. Switch it off to block every connected app at once. Nothing is disconnected: switch it back on and they carry on without signing in again. Blocked apps get 403 with a message saying so.
• Ask me before an app spends money or changes API keys. On by default. purchase_plan, top_up_balance, get_billing_portal_url, create_api_key and revoke_api_key first reply APPROVAL NEEDED with a link to platform.scriptivox.com/approvals/<id> and do nothing. After you approve, the app calls again with the same arguments plus approval_id. An approval works once, only for exactly what was asked, and expires after 24 hours. Transcription is not gated: it draws on your prepaid API balance.
• Rate limit. Each connection may make 120 requests a minute. Past that it gets 429 with Retry-After.
• Unused connections expire. A connection unused for 90 days expires and has to sign in again. Every use pushes the date out, so an app you use keeps working. The date is shown on each connection.

Troubleshooting

Prefer a key? Clients that cannot sign in can send one instead:

{
  "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: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. For 2026-07-28 there is no handshake: server/discover lists versions and capabilities, and each request carries its version in _meta. For the earlier revisions initialize echoes yours when we speak it, and otherwise answers with the newest one that still has initialize, so a client that is one revision ahead can step down rather than fail.

Besides tools, the server offers prompts (meeting-notes, transcribe-audio), the in-chat screen as an MCP Apps resource (ui://scriptivox/app), and MCP Events (events/list, events/subscribe) for signed-in apps.

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

The hosted endpoint takes either credential:

• Sign-in (OAuth 2.1). A request with no credential gets 401 with WWW-Authenticate: Bearer resource_metadata="…". MCP clients follow it on their own: they register themselves (dynamic client registration), send you to the Scriptivox consent screen, and keep a refresh token. The connection gets its own key on /keys; an expired or revoked sign-in gets 401 invalid_token, so the client refreshes or asks you again. The whole flow is written out in auth.md.
• An API key. Authorization: Bearer sk_live_…, bare Authorization: sk_live_…, or X-Api-Key: sk_live_…. Get one at /keys; see Authentication.

Cookies are ignored entirely. Credentials are used for the call and never logged or stored.

Tools

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' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -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' \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Leave the Authorization header off and you get the 401 challenge that starts sign-in.

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:

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):

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.