# Connect an AI to Cue Studio

Cue Studio has a Model Context Protocol (MCP) endpoint for AI applications that support authenticated Streamable HTTP. A paired assistant can read your scripts, prepare formatted text, and operate the prompter using the permissions you choose. The connection belongs to the operator workspace open in your browser. Version 1.10 adds browser authorization for clients that use OAuth, alongside the manual token and local stdio options.

**Endpoint:** `https://teleprompter.special.lu/api/mcp`

Keep the intended operator workspace open at [teleprompter.special.lu](https://teleprompter.special.lu/). Use OAuth when your AI client offers browser sign-in; use a manual token when it needs an Authorization header or a local stdio server. Both methods require explicit approval in **Connect devices → AI models · MCP**. A server URL or a pending authorization code alone grants no access.

## Choose your client

| Client | Connection | Setup |
| --- | --- | --- |
| ChatGPT web | Remote HTTP with OAuth | Add a custom MCP app/connection using the endpoint above; select OAuth and automatic client registration. Availability depends on your account and workspace controls. |
| Claude web, Cowork and Claude Desktop remote connectors | Remote HTTP with OAuth | Add a custom web connector; select sign-in and **Register automatically** if the client asks how to register. |
| Codex CLI, desktop and IDE | Remote HTTP with OAuth or bearer token | Configure the endpoint, then authenticate in the client or run `codex mcp login cue_studio`. |
| Claude Code | Remote HTTP with OAuth or bearer token | Add the HTTP server, then run `claude mcp login cue_studio` or authenticate through `/mcp`. |
| Cursor | Remote HTTP with OAuth | Add the endpoint to `mcpServers` in `mcp.json`, then complete its sign-in prompt. |
| VS Code / GitHub Copilot | Remote HTTP with OAuth | Add an HTTP MCP server through the Command Palette or `mcp.json`, then authorize when prompted. |
| Gemini CLI | Remote HTTP with OAuth | Set `mcpServers.cue_studio.httpUrl`, then run `/mcp auth cue_studio`. |
| Local stdio clients, including Claude Desktop's local configuration | Bundled stdio bridge with bearer token | Run `scripts/mcp-stdio.mjs` using Node and a scoped manual token. |
| Applications using an AI provider's API | Authenticated remote MCP | Supply a scoped token through the provider's documented authorization field. |

MCP support belongs to the AI application, not to a model by itself. These setup recipes follow the clients' official documentation; they are not a claim that every client version, paid plan or user account has been connected in testing. Organization administrators can restrict custom connections or tools. Cue Studio has no automatic installation into your AI accounts and is not listed in their marketplaces by virtue of exposing this endpoint.

## Connect through browser authorization

1. Add Cue Studio's endpoint in your AI client and choose OAuth or browser sign-in. Leave a client ID and client secret blank when automatic registration is available. Cue Studio uses **Dynamic Client Registration (DCR)**; choose **Register automatically** rather than a published-identity/CIMD option if the client asks.
2. The client opens Cue Studio's authorization page. It shows a **12-character approval code**. Keep that page open.
3. In your existing operator workspace, open **Connect devices → AI models · MCP**. Enter the code and select **Review**.
4. Check the client name and callback destination against the client you just started connecting. The client name is self-reported, not a verified identity. For a local CLI, the callback can be a loopback address on your own computer.
5. Choose the permissions and a lifetime of **1, 4 or 8 hours**. Read-only access is the starting choice. Use Script assistant or Operator when that matches your task; production notes have separate permissions.
6. Approve in the operator workspace, return to the authorization page, then choose **Continue to client**. The AI client receives its access token through the OAuth exchange; you do not need to copy it into chat.
7. Check the client's connection status, then ask it to read Cue Studio's authoring guide and inspect the paired workspace.

The client can request a subset of permissions. You can reduce that request, but cannot add permissions outside an explicitly requested set. If a client pins read-only scopes, change its requested scopes and authorize again before asking it to edit or operate the prompter.

Authorization requests are temporary. If the code expires, is denied, or no longer matches the request, start sign-in again in the AI client. Cue Studio does not issue refresh tokens or request `offline_access`; authorization lasts only as long as the approved pairing. After expiry or revocation, authenticate again and approve a new pairing.

## Create a manual token

1. Open the operator workspace you want the assistant to use.
2. Open **Connect devices → AI models · MCP** and name the connection so you can recognize it later.
3. Choose the access preset that fits the task: **Read only**, **Script assistant**, or **Operator**. Review the individual permissions. Production notes require their own permission and are off by default.
4. Choose a lifetime: **1, 4, or 8 hours**. The default is one hour.
5. Create the connection and copy its token into your MCP client's configuration. Cue Studio shows the token only when creating the connection; it is not saved in your workspace or backup.
6. Connect your client, ask it to read the authoring guide and current workspace, then give it a specific task.

Keep manual tokens in the client's private credentials or environment configuration. Do not put them in scripts, shared project files, public URLs or AI conversations.

## Connection lifetime and your workspace

Keep the operator tab open and connected to the relay. Reloading the operator tab, losing its relay connection, or restarting/recovering the room revokes its existing connections, including OAuth connections. Authenticate and approve again, or create and configure a new manual token. You can also revoke one connection or all connections immediately in the same panel.

Your scripts remain saved locally in Cue Studio. MCP access sends the requested information through the relay to the AI client you configure. That client's own data handling applies to what you share. The connection is not an unattended cloud copy of your workspace, and remote MCP does not work while the operator is offline.

## What the assistant can do

The endpoint exposes its current tool definitions, input schemas, read-only resources and reusable prompts. Clients can discover the available operations instead of relying on coordinates or browser clicks. A client's interface may show tools but omit the resource or prompt menus; the authoring guide is also available through a tool and on the public [AI writing guide](/ai-guide.html).

Depending on its granted permissions, an assistant can work with script content and formatting, inspect the live reading state, adjust supported prompter settings, control playback and reading position, use visual cues, and work with editor notes. Use the live tool descriptions and schemas for exact arguments, supported limits and required revision checks. Supported settings include `cueOpacity` (0–1) and `cueLayer` (`front` or `behind`) for visual cues. They apply live across updated displays, persist with workspace settings, and leave Blackout fully opaque. The operator can still control the workspace normally.

Changing a scroll mode remotely does **not** start the microphone. Microphone permissions and listening remain under the operator's browser controls. MCP cannot bypass browser requirements for microphone access, fullscreen or opening new windows, and it does not expose shell commands or local filesystem access.

| Tool family | Examples of available operations |
| --- | --- |
| Workspace and scripts | Read workspace status; search the library; read, validate, create, edit, duplicate, archive or select a script. |
| Rundown and markers | Inspect cue markers; read or update the script rundown; seek an unambiguous cue. |
| Reading and playback | Inspect settings and playback; adjust supported settings; play, pause, reset, seek, nudge, set speed or set blackout explicitly. |
| Talent cues and launchpad | Show or clear a visual cue; read the configured launchpad and activate a key. |
| Editor notes | Read takes and project details; add, update or remove takes; update project fields. |
| External speech | Feed recognized text to the external voice tracker without opening a microphone. |
| Authoring guidance | Read the guide through `cue_get_authoring_guide` or `cue://guide/authoring`; use the `write-teleprompter-script` prompt. |

### A reliable script-writing sequence

1. Call `cue_get_authoring_guide` before composing HTML.
2. Call `cue_workspace_get` and `cue_scripts_list` to identify the right workspace and script. Do not guess IDs from titles.
3. For an edit, call `cue_scripts_get` and retain the returned ETag. Validate the proposed HTML with `cue_scripts_validate`.
4. Create with `cue_scripts_create`, or edit with `cue_scripts_update` using the current `expectedETag`. Supply a fresh `invocationId`, such as a UUID, for the operation. Leave `select` false or omitted when creating unless the user asked to change the active script.
5. Read the resulting script back and report what changed. Only operate playback or send talent cues when that is part of the user's request.

All live tool schemas remain authoritative. A connection sees only the tool families its permissions allow, and individual operations can require additional permissions for optional fields such as private notes.

## ChatGPT web

In ChatGPT's custom MCP app/connection setup, enter the endpoint and choose **OAuth**. Use automatic client registration when offered; there is no client ID or client secret to obtain from Cue Studio first. Complete the browser authorization steps above, then let ChatGPT scan the tools. Enable the connection for the conversation where you want to use it.

The location and availability of custom-app creation depend on the account and workspace. If it is unavailable, a workspace administrator may need to enable it. Do not select “no authentication” as a workaround.

See the official [custom MCP setup](https://developers.openai.com/api/docs/guides/custom-mcp-server) and [OAuth authentication guide](https://developers.openai.com/plugins/build/auth).

## Claude web, Cowork and remote Desktop connectors

Open **Customize → Connectors → Add → Custom → Web**, enter Cue Studio's endpoint and choose sign-in. If Claude offers a choice of OAuth client, choose **Register automatically**. Follow Cue Studio's approval-code flow, then enable the connector in the conversation.

Remote Claude connectors are reached from Anthropic's infrastructure, even when you use its desktop app. The public Cue Studio endpoint works for this connection path; a local-only server is a different setup. Some organizations have a beta request-header option for static credentials, but the OAuth flow avoids depending on that feature.

See [Claude custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) and [Claude connector authentication](https://claude.com/docs/connectors/building/authentication).

## Codex: connect directly

For browser authorization, configure:

```toml
[mcp_servers.cue_studio]
url = "https://teleprompter.special.lu/api/mcp"
```

Then authenticate through the MCP settings in your client, or run:

```sh
codex mcp login cue_studio
```

For a manual token instead, add the environment-variable reference:

```toml
[mcp_servers.cue_studio]
url = "https://teleprompter.special.lu/api/mcp"
bearer_token_env_var = "CUE_STUDIO_MCP_TOKEN"
```

Set `CUE_STUDIO_MCP_TOKEN` in the environment available to the process that launches Codex. Its value is your current pairing token. The configuration above names the variable; it does not contain the secret. Restart or reconnect the MCP client after changing the variable.

A desktop app launched from the Dock may not inherit variables set in a terminal. Use the client's supported credential or environment setup rather than assuming a terminal export reaches the desktop process. Check the client's MCP status and ask it to list Cue Studio's tools before starting work.

See [Codex MCP configuration](https://developers.openai.com/codex/mcp/) for current client-specific instructions.

## Claude Code: connect directly

For browser authorization:

```sh
claude mcp add --transport http cue_studio https://teleprompter.special.lu/api/mcp
claude mcp login cue_studio
```

You can also use `/mcp` inside Claude Code to authenticate. If you already added a server with this name, inspect or update that configuration rather than adding a duplicate.

For a manual token instead, use this private local configuration:

```json
{
  "mcpServers": {
    "cue_studio": {
      "type": "http",
      "url": "https://teleprompter.special.lu/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CUE_STUDIO_MCP_TOKEN}"
      }
    }
  }
}
```

Set the environment variable before launching Claude Code. `${CUE_STUDIO_MCP_TOKEN}` is Claude Code's environment substitution syntax, not the token itself. Check `/mcp` after connecting. Keep private tokens out of shared `.mcp.json` files.

See [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp) for configuration scope and environment-variable behavior.

## Cursor

Add an entry to your existing `~/.cursor/mcp.json` or project `.cursor/mcp.json`, preserving its other servers:

```json
{
  "mcpServers": {
    "cue_studio": {
      "url": "https://teleprompter.special.lu/api/mcp"
    }
  }
}
```

Open Cursor's MCP controls and complete the sign-in prompt, including approval in Cue Studio. This URL-only configuration contains no secret. If your organization supplies its own MCP configuration, follow its setup policy.

See [Cursor's MCP documentation](https://cursor.com/docs/mcp).

## VS Code / GitHub Copilot

Use **MCP: Add Server** from the Command Palette and choose an HTTP server, or merge this entry into `.vscode/mcp.json`:

```json
{
  "servers": {
    "cue_studio": {
      "type": "http",
      "url": "https://teleprompter.special.lu/api/mcp"
    }
  }
}
```

Start the server, complete browser authorization and enable the tools you want in your agent's tool picker. VS Code's configuration uses `servers`, unlike the `mcpServers` wrapper used by several other clients. Trusting a server, signing in and approving individual tool actions are separate decisions.

See [VS Code's MCP setup](https://code.visualstudio.com/docs/agent-customization/mcp-servers) and [configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

## Gemini CLI

Merge this entry into Gemini CLI's MCP configuration:

```json
{
  "mcpServers": {
    "cue_studio": {
      "httpUrl": "https://teleprompter.special.lu/api/mcp"
    }
  }
}
```

Use **`httpUrl`**, not `url`: Gemini CLI uses `url` for the older SSE transport. In Gemini CLI, run:

```text
/mcp auth cue_studio
```

Complete the browser authorization flow and check that Cue Studio's tools are available. If access expires, repeat authentication and approve the new connection in the operator workspace.

See [Gemini CLI's MCP documentation](https://geminicli.com/docs/tools/mcp-server/).

## Claude Desktop and other stdio clients

The source download includes an optional bridge at `scripts/mcp-stdio.mjs`. It presents a local stdio MCP server and forwards the paired endpoint's tools, resources and prompts using the official MCP SDK. It adds no filesystem, shell or arbitrary network tools.

1. Download the [Cue Studio source archive](/source.zip) and extract it.
2. Install **Node.js 20 or newer**.
3. In the extracted project folder, run `npm ci`. This installs the versions in the supplied lockfile. You do not need to build or run the full application to use the bridge.
4. Configure your client to run Node with the **absolute path** to `scripts/mcp-stdio.mjs`.

Example Claude Desktop configuration:

```json
{
  "mcpServers": {
    "cue_studio": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/Cue-Studio/scripts/mcp-stdio.mjs"],
      "env": {
        "CUE_STUDIO_MCP_URL": "https://teleprompter.special.lu/api/mcp",
        "CUE_STUDIO_MCP_TOKEN": "PASTE_YOUR_CURRENT_PAIRING_TOKEN_HERE"
      }
    }
  }
}
```

Replace both paths with the real locations on your computer. Use `command -v node` on macOS/Linux or `where node` on Windows to find Node. On Windows, JSON paths need escaped backslashes, for example `C:\\Program Files\\nodejs\\node.exe`. The `env` object in this example is a local configuration containing a secret; keep the file private and do not commit or share it. If the client supports secure credentials, use that facility instead.

The default endpoint is the public Cue Studio URL, so `CUE_STUDIO_MCP_URL` is optional. The bridge accepts HTTPS endpoints and HTTP only on `localhost`, `127.0.0.1`, or `[::1]`. It rejects embedded URL credentials, query strings and fragments, and it does not follow redirects with your token.

Close and reopen the MCP connection after updating its token. The bridge reports unavailable or revoked connections as errors; it does not silently substitute another workspace or replay a failed change.

## Working safely during a take

Give the assistant a clear scope, such as “prepare a new script but do not start playback” or “adjust this script's emphasis and leave the reading position unchanged.” Use a read-only connection for review tasks and grant playback control only when you intend the assistant to operate the prompter.

For edits, the assistant should read the latest script or settings first and provide any required revision value with the change. If Cue Studio reports that the content changed, it should reread it and preserve the operator's newer work. It must not blindly overwrite with an old copy.

Mutating operations use invocation IDs so the relay can recognize repeated requests. A timed-out call can have an unknown outcome: the browser may have applied it before the reply was lost. Read the state before deciding what to do next, and follow the tool's retry instructions rather than creating a fresh operation blindly. A success result means the operator browser acknowledged the operation; it is not proof that a physical monitor or camera displayed it correctly.

An example instruction for your assistant:

> Read Cue Studio's authoring guide and inspect the paired workspace. Prepare a new script from my brief using supported HTML formatting, clear emphasis, and separate operator notes. Show me the resulting script and its estimated reading time. Do not change the selected script, start playback, open the microphone, or send talent cues unless I ask.

## API integrations

An application using the OpenAI Responses API or Anthropic's MCP connector can supply an authorization token through the provider's supported API field. The application must keep that token private, handle expiry and revocation, and respect the connection's permissions. Resources, prompts and write actions may be exposed differently by each host. Consult the current [OpenAI MCP API guide](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) or [Anthropic MCP connector guide](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector).

## Troubleshooting

| What you see | What to do |
| --- | --- |
| Unauthorized, expired or revoked connection | Authenticate again and approve a new OAuth pairing, or create a manual connection and replace its token in the client. |
| Operator unavailable | Keep the intended operator workspace open and relay-connected. A disconnect requires pairing again. |
| Permission denied | Check that connection's granted permissions. Create a suitably scoped connection if needed. |
| Content changed / revision conflict | Read the latest version and apply a change that preserves newer operator edits. |
| Timed out / outcome unknown | Inspect the current state before retrying a change. Do not assume it failed. |
| Tools do not appear | Check the exact `/api/mcp` URL, client connection status and approved permissions. For manual tokens, also check the token environment. A normal browser visit to the endpoint is not an MCP connection. |
| Bridge fails to start | Verify Node 20+, run `npm ci` in the extracted source folder, and check both absolute paths and the token configuration. |
| Approval code expired or unavailable | Restart sign-in in the AI client and review the new code in your existing operator workspace. |
| Client requests a published identity / CIMD | Choose automatic registration / DCR. Cue Studio does not advertise CIMD support. |
| OAuth connected but edit/control tools are missing | Review the approved permissions and any scopes pinned in the AI client's settings. Authenticate again with the needed scope and explicitly approve it. |
| Client asks for a refresh token | This release uses bounded sessions without refresh tokens. Reauthorize and approve a new pairing. |
| Custom connector option is absent | Check the AI client's account availability and organization policy. Cue Studio cannot enable features in another application. |

## Protocol and implementation notes

Cue Studio uses the official TypeScript MCP SDK v2. The HTTP endpoint serves the **2026-07-28** protocol and supports legacy initialize-based clients through the SDK's stateless compatibility mode. Ordinary calls return JSON. The stdio bridge supports both eras too; it forwards the current remote catalog instead of maintaining a separate tool list.

OAuth uses the authorization-code flow with S256 PKCE and Dynamic Client Registration. Discovery publishes protected-resource metadata and authorization-server metadata. The resource is the exact MCP endpoint; authorization and token requests are bound to it. Registered clients can use `none`, `client_secret_basic` or `client_secret_post` as their token endpoint authentication method. Redirects are checked against registered callback URIs. Native HTTP loopback callbacks may change their port while retaining their registered host, path and query; the token exchange must use the exact callback chosen for that authorization. Successful and error authorization redirects carry the authorization server's issuer.

The same seven application permissions are available through OAuth and manual pairing. OAuth discovery lists the supported scopes, while the operator makes the final permission selection. Cue Studio does not advertise Client ID Metadata Documents, OpenID Connect identity scopes, refresh tokens or `offline_access`. No Cue Studio account, email address or cloud script library is created by the authorization flow. An OAuth client registration describes the AI application and its callback configuration; it is not a workspace access grant.

The public service retains at most 512 client registrations. New, unapproved registrations expire after one hour and may be reclaimed earlier at capacity when they have no active authorization request. After the operator approves the connection, its registration lasts for 30 days without another approved authorization or token exchange. Only registration metadata and a one-way hash of a confidential client's generated secret are stored persistently; workspace content, approvals, codes and access tokens stay out of this registry. The local Node edition keeps registrations in memory. If registration expires or is reclaimed, remove and reconnect the client configuration so it can register again.

For clients that ask you to configure OAuth scopes explicitly:

| Scope | Access |
| --- | --- |
| `scripts:read` | Script library, content, validation, markers and rundown. |
| `scripts:write` | Create, update, duplicate or archive scripts and update the rundown. |
| `prompt:read` | Operator status, settings, playback state and launchpad configuration. |
| `prompt:control` | Select scripts, control playback, show cues, activate launchpad keys and feed external transcripts. |
| `settings:write` | Update supported prompter settings. |
| `notes:read` | Read production notes, project details and takes. |
| `notes:write` | Change production notes, project details and takes. |

Editing existing content usually needs its read permission as well as its write permission to obtain the current ETag. For script preparation, a useful requested set is `scripts:read scripts:write prompt:read`. Add `prompt:control` and `settings:write` only for operator work. Add notes permissions separately when the task involves production notes.

The bridge does not advertise sampling, local roots, arbitrary fetching, resource subscriptions or long-lived push notifications. Read the current state when you need it. Its HTTP credentials are restricted to the configured endpoint, and diagnostic output never includes the token.

Each pairing allows up to 120 forwarded calls per minute and four outstanding calls; the relay accepts at most 16 outstanding calls across all pairings. Calls have a 12-second acknowledgment deadline, shortened when the pairing expires. Requests and operator replies are limited to 900,000 bytes. A pairing tracks up to 256 distinct mutations without forgetting their invocation IDs: after that limit, explicitly revoke it, create a new pairing and reconnect your client. Never rotate pairings automatically to retry an unknown outcome.

For safe retries, completed mutation responses are cached only when they fit within 8 KiB per result, 256 KiB per pairing and an 8 MiB shared relay budget. Larger results are returned once; later retries receive `RESULT_REPLAY_UNAVAILABLE`, so read the current state instead of repeating the mutation with a new ID. Replaying a cached result acknowledges the earlier operation, not a new execution. Pairings and replay records disappear when revoked, expired, disconnected or when the relay restarts.

For independent integrations, use an MCP client SDK instead of treating the endpoint as a plain REST API. Modern and legacy MCP versions differ in handshake, metadata and headers. Relevant primary references are the [MCP transport specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http), [SDK HTTP guide](https://ts.sdk.modelcontextprotocol.io/v2/serving/http.html), and [SDK legacy-client guide](https://ts.sdk.modelcontextprotocol.io/v2/serving/legacy-clients.html).