MCP limits and cost

What a call costs

The tools use the same minutes as everywhere else. The first call on a video does the work and pays for it. Later calls on the same video read the stored result and cost nothing, except a summary Scribiz has not written for it yet, which uses a tenth of the video's length.

Every result reports minutesUsed, and free: true when it came from stored results and cost nothing. A failed call is not charged for work that did not happen. If ask_video reads the video (Listen or Watch) and the question then fails, the read is charged, because it was done and is stored for everyone. A call that joins a run already going, or reuses one that just finished, is not charged again. See Minutes and billing.

The local server with GEMINI_API_KEY uses no Scribiz minutes. Google bills your key. It comes with the command-line tool (npm install -g scribiz, then claude mcp add scribiz -- scribiz mcp), needs ffmpeg and yt-dlp, and is tested on macOS only.

How long a call takes

Processing a long video takes minutes, and most clients give up on a tool call after about a minute. So a tool never blocks for long:

• It waits up to 45 seconds, sending progress updates if your client asked for them.
• If the video is not done, it returns status: "processing" with a job_id and retry_after_seconds. This is a normal result, not an error.
• Calling again, or calling get_job, picks up the run that is already going.

Typical timings: a video that was processed before answers at once. A public YouTube video with captions that Scribiz has not seen takes about 8 seconds. A short video read from its link takes a few seconds (about 4 seconds for a 19 second one). Listening to a longer video takes longer than one call waits, so expect a processing result and a second call.

Tokens

A tool result is text the agent has to read, so size matters.

Lower max_chars if your client warns about large tool results. Page with cursor.

Limits

Longer videos than your plan allows are rejected before work starts.

Watch, with a key

A video that is mostly speech does not get the on-screen layer on its own. With a key you can have it, and you pay for it once.

Before anything is read, a watch: true call is quoted the way a job from the API is. It is checked against your plan's video length, the minutes you have left, and the minutes your other runs hold, and those minutes stay held while it runs. If it does not fit, it is refused at once with QUOTA or SOURCE_TOO_LONG, nothing is read, and nothing is charged. The message says how many minutes it needs. Call again without watch to leave the picture out.

A run that turns into a step you cannot pay for is stopped before that step starts. A layer that is skipped or fails is not charged. A link whose length could not be checked is read in a clip that ends at what you can still pay for; its notes are partial, they are not stored, and asking again reads again.

The picture is read once for a video. It is stored with the other layers, so the next call gets it free, with or without watch. A summary Scribiz has not written yet at that level of detail and in that language is the one thing that can still use a tenth of the video's length.

Calls at the same time for one video are taken one after the other, for one account. If you ask a question and for a summary of the same video together, the second waits for the first, finds the notes stored, and pays nothing for them. A wait that runs very long comes back as RATE_LIMIT, and the call can be repeated.

Without a key none of this applies. The picture is never looked at, a stored layer is not served, and watch is ignored with a note.

The local server (scribiz mcp, from the command-line tool, version 0.1.1 or newer) takes watch too, and serves on-screen notes that are already stored at no cost. What it costs goes to your credential: your Scribiz account's minutes after scribiz login, or Google's bill for your own Gemini key. See Connection modes.

Without a key

The server works without a key, inside a daily allowance. Days are UTC, and everything resets at 00:00 UTC.

What it does and does not do:

• It uses a video's captions when the server can read them, and serves a video Scribiz has already processed at once, however it was first read.
• When there are no captions the server can read, a model reads the video from its link. Its times are approximate (about 2 seconds either way), it has no speaker labels, and the result says so.
• It never looks at the picture, so there are no on-screen notes. A question about what was shown is answered from the words only.
• A summary written for a video that was already processed uses a tenth of its length (about 0.03 minutes for a 19 second video), and the result says so.
• If a read stops at its limit (a link whose length could not be checked in advance), the result says it is partial and how much was read. Repeating the call reads again and uses minutes again.
• One read runs at a time for each connection. A second call made at the same time waits for the first. If that takes longer than the wait, it comes back as processing and the agent calls get_job.
• When your 10 minutes, or the shared limit, are used up, captions and videos already processed still work. The error says what is used up and when it resets.
• For a video Scribiz has not processed, the link is passed to Google's model, which reads the public video. Nothing is uploaded from your machine.

Errors

A real failure is an error result, with isError: true. Its structured part has status: "failed" and an error object with the same codes the CLI and the API's jobs use, plus a message, a hint, a next_step for the agent, and retryable:

{  "status": "failed",  "error": {    "code": "URL_UNSUPPORTED",    "message": "This address is not allowed: private or loopback address (169.254.169.254)",    "retryable": false,    "stage": "resolve",    "hint": "Only public http(s) links to media or supported video sites are accepted here.",    "next_step": "Pass a public http(s) link to a video. Local files and private addresses are not available on a hosted server."  }}

A video with no speech returns a result with the warning NO_SPEECH_DETECTED, not an error.

Every engine code is described in Errors and limits.