MCP Server

Model Context Protocol (MCP) lets an AI assistant use Sovran tools. The hosted server uses your Sovran sign-in. You do not paste an API key into the client.

Start with a read request: “List my projects.” An empty workspace returns an empty list. After this check, ask for a task in your own words. Named creation tools support Creative Copilot, Voiceover Remix, Video Variations, B-roll Remix, Smart Variations, and manual variations. You do not need to supply API operation IDs.

Review the saved drafts or sequence before you estimate and export selected videos. Draft creation does not start an export. Workspace permissions, paid plan requirements, and existing charges apply.

Before you connect

Open Tools → Agent Setup. The page shows a notice when that host does not accept connections or when actions are paused. Agents can connect while actions are paused, but they cannot run actions. The MCP server URL for this host is at the bottom of the page. The production URL is https://sovran.ai/api/mcp. A development host has its own URL, account, and connections.

Workspace members with an active paid workspace plan can approve their own connections. Owners and admins can manage all workspace connections. Each connection has one workspace and a fixed permission set. MCP uses the same credits, access rules, host availability, and feature limits as the API.

An accepted invitee can use their own API key, CLI, and MCP connection. Each operation keeps the dashboard's owner and admin checks. A connection does not grant its member a higher workspace role.

Set up with one prompt

Copy this prompt and paste it into Claude Code, Codex, Claude, ChatGPT, or another agent. The agent installs Sovran where it can and walks you through the other steps. On a development host, copy the prompt from Tools → Agent Setup instead. That prompt uses the host's own server URL.

Set up Sovran in this agent. Do what you can yourself, and walk me through any step that needs me.

Sovran creates and reviews video ad drafts from media saved in my Sovran projects. Its MCP server is https://sovran.ai/api/mcp. It uses OAuth sign-in. Never ask me to paste a password or API key into this chat.

1. Find out which app you are running in. Check for an existing Sovran plugin or connection, and do not add a second one.
2. Claude Code: run `claude plugin marketplace add mansonchen29/sovran-plugin`, then `claude plugin install sovran@sovran`. Ask me to run /reload-plugins. Then ask me to run /mcp, select sovran, and sign in.
3. Codex: run `codex plugin marketplace add mansonchen29/sovran-plugin`, then `codex plugin add sovran@sovran`. Ask me to run `codex mcp login sovran` and sign in, then start a new session.
4. Claude or Cowork on the web or desktop: you cannot install plugins from chat. Tell me to open Customize → Plugins, add mansonchen29/sovran-plugin as a marketplace, install Sovran, and connect it on the plugin's Connectors tab. If my plan has no plugins, tell me to add a custom connector named Sovran with the server URL in Customize → Connectors.
5. ChatGPT: you cannot install anything from chat. Tell me to open https://chatgpt.com/plugins, select Add (+) → Add custom MCP server, name it Sovran, paste the server URL, choose OAuth, and select Create as a plugin.
6. Any other agent: add a remote MCP server named sovran at the server URL with your supported method and OAuth sign-in.
7. At the Sovran sign-in, I choose one workspace and approve Read. Sovran asks for more permissions later, only when a task needs them.
8. When the connection works, call sovran_get_profile and sovran_list_projects. Do not create, render, or delete anything.
9. Reply in 120 words or fewer: what you set up, what I still need to do, and the workspace and projects you found.

The agent stops after it reads your profile and projects. It does not create, render, or delete anything.

Connect ChatGPT

1. Open ChatGPT Plugins. Your workspace must permit custom MCP servers.
2. Select Add (+), then Add custom MCP server.
3. Enter Sovran for the name. Paste the copied MCP server URL under Connection.
4. Select OAuth. Review the notice. Select the confirmation checkbox, then Create as a plugin.
5. Follow the Sovran sign-in prompt. Choose one workspace. Keep Read selected. Select other permissions only when needed.
6. Select Approve connection. Review the tools. Install the plugin if prompted.
7. Start a new chat. Type @ and select Sovran. Ask: “List my projects.”

Your ChatGPT plan and workspace settings must permit custom MCP servers. The labels can differ by ChatGPT version.

A custom connection can use the production server while ChatGPT labels the connection as a development app. That label describes the ChatGPT listing. It does not change the Sovran server or workspace. A private connection is not a public directory listing. Customers can use the production URL through custom setup when their ChatGPT plan and workspace permit it.

Before testing a server update, select Refresh in the connection settings. Start a new chat and check the available tools. An administrator controls updates to workspace-published custom apps. Public directory plugins use OpenAI's separate review and update process. See OpenAI's connection guide and workspace app guidance.

Connect Claude

1. Open Customize → Connectors. Select Add → Add custom connector. For Team or Enterprise, an administrator first uses Organization settings → Connectors → Add → Custom → Web.
2. Enter Sovran for the name. Paste the copied MCP server URL. Select Continue.
3. Review the detected authentication settings. Select Continue. Choose Sign in now and Register automatically.
4. Select Add, then Connect. Follow the Sovran sign-in prompt.
5. Choose one workspace. Keep Read selected. Select other permissions only when needed. Select Approve connection.
6. Open a chat. Use + → Connectors to enable Sovran. Ask: “List my projects.”

Your Claude plan and workspace settings must permit custom connectors. An organization must give its members access to the connector first. Each member then selects Connect in Customize → Connectors. Client labels can change. See Claude's connection guide.

Install the plugin

The Sovran plugin connects the same production server. It also adds a skill that tells the agent which flow to use, when to stop for your review, and how to check jobs. The plugin works in Claude Code, Claude, Cowork, and Codex. It is not listed in Claude's directory. Install it from its public repository, mansonchen29/sovran-plugin.

In Claude Code:

1. Run /plugin install sovran --marketplace mansonchen29/sovran-plugin. Before Claude Code 2.1.275, run claude plugin marketplace add mansonchen29/sovran-plugin, then claude plugin install sovran@sovran.
2. Run /mcp. Select sovran and sign in to Sovran.
3. Choose one workspace. Keep Read selected. Select Approve connection.
4. Ask: “List my Sovran projects.”

In Codex:

1. Run codex plugin marketplace add mansonchen29/sovran-plugin.
2. Run codex plugin add sovran@sovran.
3. Run codex mcp login sovran. Sign in to Sovran, choose one workspace, and select Approve connection.
4. Start a new Codex session. Ask: “List my Sovran projects.”

In Claude or Cowork, open Customize → Plugins. Add mansonchen29/sovran-plugin as a marketplace and install Sovran. Then connect Sovran on the plugin's Connectors tab. For Team or Enterprise, an Owner can add the marketplace for the whole organization.

To update the plugin, run claude plugin update sovran@sovran in Claude Code or codex plugin marketplace upgrade sovran in Codex. The plugin does not change your permissions or existing connections.

Choose permissions

The server requests only Read for the first connection. A task that needs more permissions starts a new consent request. That request keeps the permissions you approved earlier. A client can also request other supported permissions during connection.

• Read reads projects, assets, jobs, usage, and the connected profile. It is required.
• Write creates and updates content.
• Generate generates media and renders videos. Existing credit charges apply.
• Delete deletes content that your account can delete.
• Publish publishes through accounts connected in Sovran.

The named tools include their request and result rules. Use them for the flows below. For other tasks, the assistant can find operations with task words such as video editor, video variations, voiceover remix, b-roll remix, or sequence videos. It can read the shared rules with sovran_describe_operation. The editor descriptor includes field rules and small overlay examples. Use the call tool for the required permission when calling an API operation.

releaseAvailable shows whether this host permits an operation. It does not prove that the connection has access. Permissions, the paid plan, feature flags, and runtime rules still apply.

Ask the assistant to list your projects first. An empty workspace returns an empty list. If a call needs more permissions, Sovran returns the required permissions and an HTTP 403 consent challenge before the action runs. Follow the client's sign-in prompt. If no prompt opens, reconnect Sovran in client settings and approve the required permissions with new consent. An existing token cannot gain new permissions or change its workspace.

Start a video task

The server has 32 named task tools. It also keeps the eight existing discovery and call tools. Both sets use the same workspace access, schemas, credits, and release rules.

The assistant starts with sovran_get_profile. It then uses sovran_list_projects and sovran_list_assets to find your project and sources. If a project name has more than one match, select the project before creation. An empty source list means that the assistant must stop and report the missing footage.

The other 25 named tools support discovery, review, and export:

Named tools take resource IDs as top-level fields, such as projectId or compositionId. Request settings stay in body. List filters stay in query. A change also takes a top-level idempotencyKey. The assistant must keep the exact submitted values. It must not add omitted defaults before replay.

Creation and export are separate tasks. The assistant must show saved draft names and their editor links before export. Open the links to review the drafts. Select the drafts or combinations to export. An editor link opens a saved draft in Sovran. It is not a finished video link.

Only estimate the selected exports. An estimate reads the output count and credit cost. It does not create finished videos. Submit an export after you approve the selected items and the reported cost.

Jobs, uploads, and downloads

A job request returns its public job ID. The assistant can check that job with sovran_get_job. MCP does not wait for a long render. A native run ID, draft ID, or render ID is a different resource ID.

Upload operations return the existing signed upload instructions. Download operations return signed URLs. Their expiresAt value is the link expiry. It does not delete the saved video. Read the output again to get a fresh link without a new render. The hosted server cannot read local files. It does not send full media files inside MCP messages. Use Install CLI + Skill for local file transfers.

Changes require a request token that prevents duplicate work. Save it with the exact named tool and arguments. For an existing call tool, save the exact operation, path, query, and body. Replay that exact request only to read its saved acceptance. A confirmed failed job can use its supported retry operation with a separate saved token. Do not retry automatically.

Read jobs while their status is queued, running, or waiting. Use a limited wait. If the wait ends, keep the public job ID and read the same job later. Stop polling when the job reaches another status. Read saved outputs and child job results before reporting a final count. partially_succeeded means that some work succeeded. Keep its saved drafts. requires_action and manual_review require the reported next action. A chat that ends does not cancel accepted work.

If a job returns requires_action, read its error and nextAction. When retryAllowed is false, do not submit a new retry. If an export submission is uncertain, contact Sovran support with the job ID. A new request token can create duplicate work.

Create remixes and variations

Use Read and Generate for draft creation and export. Manual sequence creation and configuration also need Write. Use Write when the assistant must create a project or upload assets. Choose resources from the connected workspace. Named tools include their schemas. The existing call tools still require an operation description before a request.

For Voiceover Remix, ask the assistant to use sovran_list_voiceovers, which calls get__projects_projectId_voiceovers. Select items with status succeeded. Each item's id is the native voiceover ID for voiceoverJobIds. When present, its publicJobId identifies the generation job for polling. Each voiceover must be 5–120 seconds long and have ready audio, timed words, and an SRT caption file. Select one to three unique voiceovers. Choose draftsPerVoiceover: 1, 3, or 5. This count is required. One batch can create at most 15 drafts. Saved voiceovers are reused. The list leaves out voiceovers removed from the saved library, because Voiceover Remix rejects them. A batch with two or three voiceovers returns one public job per voiceover in jobIds; the assistant reads each one.

For Video Variations, choose four, six, or eight outputs. The default is four. The default minimum length is 15 seconds. The default format is 9:16 with captions enabled. Each story creates a clean draft and a draft with opening text. The source needs at least five seconds and ten spoken words in its timed transcript. General media renderReady does not prove that this speech requirement is met. Ask the assistant to list sources with requireTranscript set to true; that list holds only videos with ready speech. Creation checks the selected source again. The job also prepares speech audio to remove background audio. A short source can fail to supply enough distinct complete stories.

For B-roll Remix, choose one, three, or five drafts per hook. This count is required. Use selected footage or all eligible project footage. Opening text can be absent, manual, or selected from saved hooks. Choose no music for silent drafts or automatic music selection. An omitted musicMode uses no music. Automatic music can use project tracks or import a permitted library track. Check the saved draft before export.

Ask the assistant to use the named creation tool for the chosen flow. The existing sovran_call_generate remains available for API operations. Save the exact request and idempotencyKey. Poll only the returned public job with sovran_get_job, or sovran_call_read and get__jobs_jobId. Read any reported child job before you assess the final output count. Do not start another creation request while the first result is unknown.

Voiceover Remix supports public job retry and named saved batch retry. Both routes resume the same saved checkpoint. B-roll Remix creation does not support generic job retry. POST /jobs/{jobId}/retry returns HTTP 409 with retry_not_allowed for B-roll jobs. Their response includes retryAllowed: false and nextAction. Replaying the exact original creation request only reads its saved acceptance. Do not submit a new creation token to restart a failed remix. Read the saved batch retry rules below before a Voiceover retry. If no supported retry is available, contact Sovran support with its public job ID.

These flows save editable drafts. The public job returns their IDs in outputEditorProjectIds. Your client must enable Write and Generate actions for creation requests.

For Audience variations, ask the assistant to use sovran_find_audiences on one project video. It returns an analysisId. The assistant reads it with sovran_get_audience_analysis until its status is ready, then shows each audience with its callout and evidence. Approve one to three audiences. The assistant then calls sovran_create_audience_variations with the same video, the analysisId, and each approved audience's id, name, and callout. Each approved audience makes one draft. Audience analyses and audience drafts share a daily limit.

For Smart Variations, use sovran_preview_smart_sources, which calls post__projects_projectId_smart_drafts_source_preview. It needs Read permission and does not generate media. Check sources.ready and any reference.valid value. success: true means that the preview read completed. Use sovran_create_smart_variations, which calls post__projects_projectId_smart_drafts, to create 5, 10, or 20 editable drafts from saved project speech. draftCount is required. Defaults are 9:16, a 15-second minimum, captions enabled, a required CTA, and balanced variations. Poll the accepted public job. Use get__projects_projectId_smart_drafts for native run IDs. Use sovran_get_smart_run with the native ID as resourceId to call get__smart_drafts_resourceId. This read returns available outputs and original selection ranges.

A fixed section request uses lockedDraft.jobId from the native run id, its saved combinationId, and vary: "hook" or "body". vary: "hook" creates new hooks and keeps the body and CTA. vary: "body" creates new bodies and keeps the hook and CTA. It retains the original ranges. Later composition edits do not alter this reference. The selected source footage must still be ready and match the filters.

Generic job retries are not available for native Smart Variations drafts. POST /jobs/{jobId}/retry returns HTTP 409 with retry_not_allowed. The job response includes retryAllowed: false and nextAction. If a run fails, contact Sovran support with its public job ID. Replay the exact original request to read its saved acceptance. Do not use a new request token to resume a failed run. Its separate saved cancel and resume controls are described below.

For Arrange clips in Modular Builder, use sovran_create_manual_variations to create a sequence. Read it with sovran_get_sequence. Use sovran_replace_sequence_configuration to replace the blocks and tracks. Include all values to retain in that replacement. Read combinations with sovran_list_combinations. Review and select their IDs before an estimate. There is no draft-count preset. Block and track choices determine the output count. One public render request allows at most 100 outputs. The existing sequence smart-variations operation checks combination coherence. It returns combination decisions instead of creating native Smart drafts.

A sequence batch can contain plain combinations and compatible saved row edits. The server uses the current caller's saved combination-to-editor mappings. It checks the mapping, editor revision, saved state, and configuration fingerprint again before acceptance. Edited selections permit at most one music track and one voiceover. Changed mappings or revisions require a fresh estimate. Export other saved compositions separately. Do not send arbitrary composition IDs or timeline overrides in a sequence render request.

For both Manual and Smart sequence batches, use get__projects_projectId_assets, post__projects_projectId_sequences, and put__sequences_sequenceId_configuration for setup. Read get__sequences_sequenceId_combinations for current combination IDs, sequenceUpdatedAt, and inputFingerprint. Smart mode first calls post__sequences_sequenceId_smart_variations with the current revision. Poll its public jobId, then read get__sequences_sequenceId_smart_variations_resourceId with its analysisId. Choose saved approvedCombinationIds. An empty approved list supplies no Smart batch to export.

Saved Smart rejection reads keep decision fields and saved asset references. A rejection with no saved references has assets: []. The server does not replace these with assets from the current sequence. To export selected combinations, use sovran_estimate_sequence_export, which calls post__sequences_sequenceId_render_estimate. Review its cost and outputCount. Submit the same settings with planFingerprint through sovran_export_sequence, which calls post__sequences_sequenceId_renders. Keep the current revision, input fingerprint, and caption style. See the sequence batch guide.

For Creative Copilot, use sovran_list_copilot_templates to read built-in or saved project templates. The existing reads are get__auto_edit_brief_templates and get__projects_projectId_auto_edit_templates. Send a built-in id as briefTemplateId to sovran_create_creative_copilot, which calls post__projects_projectId_auto_edits. An omitted brief uses the chosen template's instructions. The custom item requires a brief. To use a saved project template, pass savedTemplate: {id, revision}. Stored instructions and settings apply before defaults. Explicit request fields override those settings. Omit a setting to keep its saved value. For a project rough cut, use sourceMode: "project_story", briefTemplateId: "project_story", and a brief. Omit sourceAssetIds in that mode. The service selects ready project speech videos.

Copilot hook variations accept hookVariationCount: "auto", 3, 4, 5, or 6. The default is "auto". Video Variations accept videoVariationCount: 4, 6, or 8. Voiceover and B-roll counts use the presets above. For custom Copilot, the default target is 30 seconds. To make two finished videos, choose a supported creation count and export two selected saved drafts. Do not send an unsupported draft count of 2.

To export a selected draft:

1. Read it with sovran_get_draft, which calls get__compositions_compositionId. Open its editor link. Select it after review.
2. Use sovran_estimate_draft_export to call post__compositions_compositionId_render_estimate. Use its current updatedAt as expectedUpdatedAt and maxOutputs: 1.
3. Review the output count and credit cost. Save planFingerprint from the estimate.
4. Use sovran_export_draft to call post__compositions_compositionId_renders. Keep the same revision and export settings. Add that fingerprint and a new saved request token.
5. Poll the returned public render job with sovran_get_job. Use sovran_get_render_outputs to call get__renders_renderId_outputs with its output renderId.

For Arrange clips combinations, use sovran_estimate_sequence_export and sovran_export_sequence. Send only the selected combinationIds, or useSavedShortlist: true to build the shortlist saved in the dashboard. Use sequenceUpdatedAt as expectedUpdatedAt. Keep that revision, inputFingerprint, settings, and the returned planFingerprint through both steps. A changed sequence or export plan requires a fresh estimate. Add aspectRatios to build several formats; each format is a separate output and credit. useProjectSettings: true uses the project Build settings for formats, captions, and export quality.

To render several reviewed drafts from one project, use sovran_estimate_drafts_export with up to ten draft IDs, then sovran_export_drafts with the returned planFingerprint. Read progress with sovran_get_drafts_export, and finished links with sovran_get_render_outputs. Draft creation does not produce a finished video. The creation guide gives request examples and source rules.

Read ready outputs again when their signed url expires. Use expiresAt to check the expiry. This read does not create a new render. Confirm each terminal result and inspect partial success before reporting the final video count.

Voiceover history, batch reads, rename, and saved checkpoint retry use get__projects_projectId_voiceover_remix_batches, get__projects_projectId_voiceover_remix_batches_resourceId, patch__projects_projectId_voiceover_remix_batches_resourceId, and post__projects_projectId_voiceover_remix_batches_resourceId_retry. These operations exclude B-roll. Retry only when the saved batch reports retryStatus.state: "eligible". A public job can report retryAllowed: true for a failed native job with a saved batch and remaining retries. That field alone does not prove that cooldown and other batch checks permit a retry.

Choose one retry route per failure. post__jobs_jobId_retry takes the original public Voiceover Remix jobId and {}. It returns HTTP 202 with that same public jobId. Poll it with get__jobs_jobId. The named batch retry takes the saved batch ID as resourceId and {}. It returns native jobIds; track them through the batch read. Do not use these native IDs as public job IDs. Save a separate token for the selected route. Do not call both routes for the same failure.

Both routes resume at most two failed native jobs per request. Each job permits at most three retries. Only one retry can be active per project. Requests are at least one minute apart. Saved plans, audio, captions, and successful drafts remain. Neither route creates a new public generation job. Replay the selected route's exact request and token after an unknown result.

Named draft cleanup with kind: "voiceover_remix" also excludes B-roll. Generic draft IDs and kind: "auto_edit" cleanup still support both. Read post__projects_projectId_draft_cleanup_impact before delete__projects_projectId_draft_cleanup. Use the same target and returned fingerprint. B-roll history uses get__projects_projectId_broll_remixes.

Sequence exports permit at most three explicit retries through post__jobs_jobId_retry. Composition export chains permit the original export and at most two explicit retries. Retry only confirmed failures after the charge and refund checks pass. These exports and remix creation have no generic cancellation operation. Closing a chat does not cancel accepted work. Native Smart draft runs have their own saved cancel and resume controls. See history and cleanup for those operation IDs.

Manage a connection

Open Agent Setup, then Connections below the setup card. Check the client, workspace, permissions, approving user, status, last use, and expiry. Hover over or focus a date to see the full time and time zone.

The approving user must remain a workspace member. If that user leaves the workspace, the connection shows Blocked. New requests and token refresh fail. Ask a current workspace member to reconnect and approve access. You can disconnect the blocked connection.

Select Disconnect, then Confirm disconnect, to block new calls and token refresh. The confirmation moves keyboard focus to Cancel. Select Cancel to keep the connection and return focus to Disconnect. Work already accepted can continue. A connection expires 30 days after approval. Start a new connection when it expires.

If MCP access is closed, connections cannot make requests. You can still disconnect a saved connection. Connect Meta or TikTok in Account settings before publishing.