Skip to content
Braiv Docs

MCP

Braiv hosts a Model Context Protocol server for agents and IDEs. It exposes Public API v1 as tools. You sign in with OAuth (Authorization Code + PKCE) — the same Braiv Studio account — instead of pasting an API key into config.

HTTP integrations keep using API keys. MCP for customers uses OAuth.

Endpoint

Section titled “Endpoint”
https://mcp.braiv.co/mcp
TransportStreamable HTTP
Authorization serverhttps://api.braiv.co
DiscoveryGET https://mcp.braiv.co/.well-known/oauth-protected-resource

Your client must support Streamable HTTP and OAuth 2.1 (Authorization Code + PKCE). Dynamic Client Registration is supported. Do not put braiv_live_… keys in MCP config when the client can Connect with OAuth.

Cursor

Section titled “Cursor”
  1. Open Cursor Settings → MCP (or edit ~/.cursor/mcp.json / project .cursor/mcp.json).
  2. Add a remote server with only the URL:
{
  "mcpServers": {
    "braiv": {
      "url": "https://mcp.braiv.co/mcp"
    }
  }
}
  1. Enable the server. Cursor discovers OAuth from the resource metadata and prompts you to Connect.
  2. Complete sign-in on Braiv (Google or email/password — same as Studio). If you belong to team workspaces, choose Personal or a team library on the workspace picker (home / licensed workspaces are preselected when possible).
  3. When Cursor finishes the redirect, tools appear under the Braiv MCP server. Start a new chat if an old session still shows a cached tool list.

Claude (Desktop, claude.ai, Cowork)

Section titled “Claude (Desktop, claude.ai, Cowork)”

Remote MCP on Claude uses custom connectors, not a URL field inside claude_desktop_config.json (that file is for local stdio servers).

  1. Open Settings → Connectors → Add custom connector.
  2. Name it (for example Braiv).
  3. Remote MCP server URL: https://mcp.braiv.co/mcp
  4. Leave advanced OAuth client id/secret empty unless Braiv gives you a static client — Dynamic Client Registration is the default.
  5. Save, then complete the Braiv sign-in when prompted.
  6. Start a new chat so tools appear.

The connection is brokered through your Claude account (Anthropic’s cloud talks to Braiv). Free plans may limit how many custom connectors you can add.

Optional: mcp-remote bridge (stdio)

Section titled “Optional: mcp-remote bridge (stdio)”

If you must use claude_desktop_config.json instead of Connectors (for example a local-only workflow), bridge Streamable HTTP with mcp-remote. Prefer Connectors + OAuth when possible.

{
  "mcpServers": {
    "braiv": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.braiv.co/mcp"]
    }
  }
}

Restart Claude Desktop after editing. mcp-remote will run the OAuth flow in a browser when needed.

Claude Code

Section titled “Claude Code”

Project or user .mcp.json:

{
  "mcpServers": {
    "braiv": {
      "type": "http",
      "url": "https://mcp.braiv.co/mcp"
    }
  }
}

Or from the CLI (if your Claude Code build supports remote HTTP add):

Terminal window
claude mcp add --transport http braiv https://mcp.braiv.co/mcp

Complete OAuth when the client opens Braiv sign-in. Use type: "http" (not streamable-http) — that is the documented Claude Code value for Streamable HTTP with SSE fallback.

VS Code (GitHub Copilot)

Section titled “VS Code (GitHub Copilot)”

Requires a recent VS Code with Copilot Agent / MCP support (1.101+ recommended).

Workspace .vscode/mcp.json or user MCP config (MCP: Open User Configuration):

{
  "servers": {
    "braiv": {
      "type": "http",
      "url": "https://mcp.braiv.co/mcp"
    }
  }
}

Note the root key is servers, not mcpServers. On first use, VS Code opens a browser for OAuth. Use Agent mode in Copilot Chat so tools are available.

Static OAuth clientId is optional; omit it and let Dynamic Client Registration run unless your admin requires a pre-registered client.

Windsurf

Section titled “Windsurf”

Edit ~/.codeium/windsurf/mcp_config.json (or the MCP settings UI). Remote servers use serverUrl:

{
  "mcpServers": {
    "braiv": {
      "serverUrl": "https://mcp.braiv.co/mcp"
    }
  }
}

Complete Braiv OAuth when prompted. If your Windsurf build only supports a Bearer header and not OAuth Connect, use an API key fallback or the mcp-remote bridge below.

ChatGPT and other OpenAI hosts

Section titled “ChatGPT and other OpenAI hosts”

Where the product supports remote MCP connectors (custom GPT / developer MCP URL), set the server URL to https://mcp.braiv.co/mcp and complete Braiv OAuth when the host starts the authorization flow. Exact UI labels vary by product; the endpoint and issuer stay the same.

Grok (grok.com / Grok Bot)

Section titled “Grok (grok.com / Grok Bot)”

Add a custom connector at grok.com/connectors with:

https://mcp.braiv.co/mcp

Complete Braiv sign-in when Grok prompts. Grok’s cloud broker re-sends the Bearer on later calls; if Connect never finishes, every turn looks unauthenticated. Reconnect the connector after you sign in. If the Grok client allows a static header instead of OAuth, use an API key fallback.

Other clients

Section titled “Other clients”

Any client that speaks Streamable HTTP MCP + OAuth 2.1 PKCE can use:

https://mcp.braiv.co/mcp

Redirect URIs must be https://…, http://localhost… / http://127.0.0.1…, Cursor’s desktop callback, or Grok/xAI custom-scheme callbacks on grok.com / x.ai. After Connect, trust the live tool list the client shows.

mcp-remote (generic stdio bridge)

Section titled “mcp-remote (generic stdio bridge)”
{
  "mcpServers": {
    "braiv": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.braiv.co/mcp"]
    }
  }
}

Requires Node 18+. Useful when the host only launches local processes.

API key fallback

Section titled “API key fallback”

Prefer OAuth for hosted MCP. If a client cannot complete OAuth, you can send a Studio API key on the Streamable HTTP requests:

{
  "mcpServers": {
    "braiv": {
      "url": "https://mcp.braiv.co/mcp",
      "headers": {
        "Authorization": "Bearer braiv_live_…"
      }
    }
  }
}

Adapt field names (url vs serverUrl, mcpServers vs servers) to the host. Create keys in Studio with the scopes you need. Keys remain the right auth for direct /v1 HTTP clients.

What you get after Connect

Section titled “What you get after Connect”

Tools wrap Public API operations (operationId in OpenAPI). Names are prefixed braiv_ (for example braiv_list_videos → listVideos).

AreaExamples
Healthbraiv_health
Librarylist/get videos, transcripts, subtitles, dubs, shorts, thumbnails, packaging, characters, brand voices, folders
Speechbraiv_list_voices / braiv_get_voice (always); braiv_add_voice, braiv_text_to_speech, braiv_delete_voice when mutate is on
Jobslist/get jobs, poll until ready
Creditsquote
Productscreate import/upload, prepare local upload, dubs, shorts, thumbnails, packaging, professional hosting, downloads, caption translate, folders
Webhookslist/create/delete endpoints

Thumbnail generation: list braiv_list_characters and braiv_list_brand_voices, then pass a CreateVideoRequest / CreatePackagingRequest / CreateThumbnailRequest body from OpenAPI. Creative is pipelineMode: thumbnail-v2 (not a creative enum). Precision is thumbnail-precision plus autoDetectContentReferences or explicit content plate URLs. See Generate a thumbnail.

Library folders: braiv_list_folders / braiv_get_folder, then braiv_create_folder (mutate) with optional parentId for a subfolder. Pass the returned id as folderId on import. Nesting is limited to 3 levels. The reserved Studio folder All Videos is not listed and cannot be a parent.

Professional hosting: braiv_get_professional_hosting, then braiv_activate_professional_hosting (mutate) to turn on Mux for a library video. Poll get until status is ready. Requires a Pro or Business plan. See Activate professional hosting.

Speech voice_id values are voice clones from GET /v1/voices, not Brand Voice ids. After braiv_add_voice, poll braiv_get_voice until status is ready before braiv_text_to_speech. Connect tokens (oat_) now authorize Speech as well as Public API. Requires tts:read / tts:synthesize / tts:write as listed in scopes.

Cursor shows the live tool list for your session. Prefer braiv_get_job loops over long blocking polls when the client times out.

Signed download and audio URLs are redacted in tool output so agents do not echo secrets into chat.

Local files: hosted MCP cannot read the user’s disk. Use braiv_prepare_local_upload (or createVideo + braiv_create_video_upload) to get a 30-minute GCS resumable start URL (not redacted). From the machine that has the file: POST that URL with x-goog-resumable: start, then PUT bytes to the Location header. Repeat once per file, then poll import_{videoId}. See Upload a file.

Auth and scopes

Section titled “Auth and scopes”

OAuth grants the same scopes model as API keys. Access tokens are oat_… Bearers; they are not Firebase ID tokens.

Plan gate matches the Public API (Pro and above). Credits and rate limits are the same as HTTP — see Credits and Rate limits.

Workspace selection happens on Connect when you have team memberships: the OAuth token’s workspaceId binds library and billing for that session (personal stays null). To switch libraries, disconnect and Connect again, or use a workspace-scoped API key on /v1.

Section titled “Related”