# MCP connection modes

> Remote without a key, remote with an API key, the local server with your account or Gemini key, and OAuth coming later. What each can do and which to pick.

Page: https://scribiz.com/docs/mcp/connection-modes

The server can be reached four ways. Three are open today. Remote with no key is open to everyone. Remote with a key needs an API key from your account. Local runs on your machine from the command-line tool, with your Scribiz account or your own Gemini key. OAuth is not built yet.

| Mode | How you connect | Listen and Watch | Local files | Works in |
| --- | --- | --- | --- | --- |
| Remote, no key | URL only | No Watch. Captions, videos already processed, and a model read of the link | No | Any client that takes a URL. We have tested claude.ai, not ChatGPT |
| Remote, with a key | URL and `Authorization: Bearer` | Yes, from your minutes | No | Claude Code, Cursor, VS Code, Codex, agent SDKs |
| Local | `scribiz mcp` started by your client | Yes, with your Scribiz account or your own Gemini key. It takes `watch: true` and serves stored on-screen notes, like the remote server with a key | Yes, from folders you allow | Any client that starts a command |
| OAuth, coming later | URL and a sign-in | Yes, from your minutes | No | claude.ai, Cursor |

## Remote, no key

Paste `https://scribiz.com/mcp` into a client and it works. There is nothing to sign up for.

What you get:

- Captions, when our server can read them. Up to 30 caption lookups a day, counted per connection.
- Results Scribiz has already stored for a video, at no cost, however they were first read. The one exception is a summary Scribiz has not written for it yet, which uses a tenth of the video's length.
- When there are no captions our 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.
- 5 questions a day with `ask_video`, 0.1 minute each.

That reading uses the same 10 minutes a day as the free web tool, for videos up to 15 minutes. It is charged by the length of the video that was actually read, so a 19 second video uses about 19 seconds of your 10 minutes. Captions use a tenth of that. A video known to be longer than 15 minutes is refused before anything is used.

What you do not get is Watch. The server never looks at the picture, so there are no on-screen notes, and a question about what was shown is answered from the words only.

Everyone who connects without a key also shares one more daily limit. It is separate from the website's free tools: neither can use up the other's. When your 10 minutes or that shared limit are used up, captions and videos already processed still work. The error says what is used up and that it resets at 00:00 UTC. See [Limits and cost](https://scribiz.com/docs/mcp/limits.md#without-a-key).

## Remote, with a key

Send your API key as a bearer token, or in an `X-API-Key` header. Keys are made in the dashboard, after you sign in with an email link. Give a key the `mcp` scope if it will only be used for this.

```text
Authorization: Bearer sbz_live_your_key_here
```

This unlocks Listen, Watch and Both, counted in your plan's minutes. A key with the `mcp` or `all` scope works. A bad key is `401`, and a key with only the `read` scope is `403`. A session token from the website is not accepted. The same key works for the API, and calls from both share one balance.

Clients that accept a custom header work with a key: Claude Code, Cursor, VS Code, Codex and the agent SDKs. claude.ai signs in with OAuth rather than a key. For it, use the keyless URL today and OAuth when it ships.

## Local

`scribiz mcp` runs the server on your machine over standard input and output. Your client starts it as a command. It comes with the command-line tool: run `npm install -g scribiz`, then `scribiz login` to use a free Scribiz account, or `scribiz setup` to save your own Gemini key. It needs Node.js 24 or newer, `ffmpeg` and `yt-dlp` (see [Install the CLI](https://scribiz.com/docs/cli.md)), and only macOS has been tested. The `watch` argument and stored on-screen notes need `scribiz` 0.1.1 or newer.

```bash
claude mcp add scribiz -- scribiz mcp
```

Choose it when:

- The video is a file on your disk. Add `--allow-files`, and `--root` for each folder the agent may read. Without `--root`, the current folder is the one allowed folder, except `/`, your home folder or a folder above it: a client that starts the server in one of those must pass `--root`.
- The site blocks servers (TikTok, Instagram, and others). The local server fetches from your connection.
- You want to use your own Gemini key. Audio goes from your machine to Google, and no Scribiz minutes are used.
- You want your free account's minutes (30 a month) in an agent on your machine, with no API key to make. Audio goes from your machine to Scribiz, which sends it to Google.

It reads the same credential as the CLI, and the first match wins: `SCRIBIZ_API_KEY`, then `GEMINI_API_KEY`, then what `scribiz login` or `scribiz setup` saved. One credential is saved at a time. The credential is read on every tool call, so a sign-in you save after the client started is picked up. If `GEMINI_API_KEY` is set in the environment your client starts the server with, it wins over a saved sign-in. See [Authentication](https://scribiz.com/docs/authentication.md#which-credential-wins).

With an account and no minutes left, a tool call returns the error `QUOTA` and says when your minutes come back. Your own Gemini key is the other way.

### Watch and on-screen notes

The local server takes the `watch` argument on `get_video_context` and `ask_video`, the same as the remote server with a key. `watch: true` reads the picture too (slides, code, text on screen), even when the video is mostly speech. On-screen notes that are already stored come with the result at no cost. Both are described on [Tools](https://scribiz.com/docs/mcp/tools.md#watch-with-a-key). What a read costs is paid by your credential: your account's minutes with a Scribiz sign-in, or Google's bill with your own Gemini key.

### What is different from the remote server

| | Remote, with a key | Local |
| --- | --- | --- |
| Runs on | Scribiz's servers | Your machine |
| Credential | An API key from the dashboard | `scribiz login` or `SCRIBIZ_API_KEY` (your account), or `scribiz setup` or `GEMINI_API_KEY` (your own Gemini key) |
| Counted in | Your plan's minutes | Your account's minutes with a Scribiz sign-in. With your own key, Google bills it and no Scribiz minutes are used |
| Where the audio goes | Scribiz, then Google | With a sign-in: your machine, then Scribiz, then Google. With your own key: your machine, then Google |
| Fetches links from | Scribiz's servers | Your own connection |
| Local files | No | Yes, from folders you allow |
| Private addresses | Not available | Refused unless you pass `--allow-private-network` |
| `watch: true` and stored on-screen notes | Yes | Yes |
| Without a credential | A small daily allowance, no picture | The server starts and says on standard error that tool calls will fail until there is a credential. Each call answers `AUTH` until you sign in or save a key |

The remote server with a key is the one to use when you do not want to install anything. The local server is the one to use for files, for sites that block servers, and to run with your own Gemini key.

The model that calls the server may have read a page that told it to fetch a link. So the local server refuses links to your own machine and to private networks (`localhost`, `192.168.x.x`, `*.local`, a cloud metadata address), and pages that only the generic reader of `yt-dlp` handles. Direct media links, YouTube, Instagram, TikTok, Vimeo and X work. `--allow-private-network` lifts both rules.

```bash
scribiz mcp --allow-files --root ~/Recordings
```

```text title="Standard error, once the server is ready"
scribiz mcp: ready on stdio · files allowed under /Users/you/Recordings
```

A path outside the allowed folders is refused:

```text
Scribiz error INPUT_UNSUPPORTED (not retryable): That file is outside the folders this server may read
Hint: Allowed folders: /Users/you/Recordings. Move the file there or start the server with another --root.
```

## OAuth, coming later

claude.ai signs in with OAuth. It is not built yet. When it ships, adding the URL will open a Scribiz sign-in and consent page, and the connection will appear in your dashboard, where you can revoke it.

Until then:

- To use Listen and Watch from claude.ai, there is no supported way yet.
- To use Listen and Watch from a coding agent, use a key, or the local server.
- To read a video from claude.ai, use the keyless URL.

## Which one

| You want | Use |
| --- | --- |
| To try it in ten seconds | Remote, no key |
| An agent in Claude Code, Cursor or VS Code that needs to look at the picture | Remote, with a key |
| To use files on your disk | Local |
| To use a video from a site that blocks servers | Local. Or download the file and upload it on the web |
| To avoid Scribiz minutes | Local, with your own Gemini key |
| To use your free account's minutes on your own machine | Local, signed in with `scribiz login` |
| claude.ai with Listen and Watch | Not yet. Wait for OAuth |

---

Checked against the Scribiz build on 2026-10-05.