Skip to content
EditorBrainDocsEspañolOpen EditorBrain ↗

Developers

Connect agents with MCP

Steps for Claude and Codex, a connection check, and help when something fails.

Download Markdown ↗

Connect EditorBrain to Claude or Codex so your agent can read your brand, your projects and the editing instructions. You do not need to install the CLI or the skills separately.

Choose your app, connect your account and check access. To install the CLI in a folder, use the other path in Install and connect.

Connect from Claude

These steps work for Claude on the web and desktop, including the Code tab. If you use Claude Code in the terminal, use the commands in "Terminal setup" at the end of this guide.

  1. Open Connectors in Claude. Depending on the version, it may be under Settings or Customize.

  2. Add a custom / web connector. Use EditorBrain as the name and paste this URL:

    Command
    https://api.editorbrain.com/mcp
    
  3. Save the connection. In the window that opens, sign in to EditorBrain and authorize the workspace where your projects live.

  4. Go back to Claude and turn EditorBrain on in the chat connectors. If the tools do not appear, open a new chat.

  5. Copy the check message below.

Connect from Codex

  1. Open Codex MCP servers settings and add a server.
  2. Choose HTTP / remote server, use EditorBrain as the name and paste https://api.editorbrain.com/mcp.
  3. Save and use Authenticate if it appears. Sign in to EditorBrain and authorize your workspace.
  4. Return to Codex; reload the agent if it asks.
  5. Copy the check message below.

Menu names can vary by client version. If the custom connector option does not appear, check your account's availability or your organization's permissions; it is not an error in your projects.

Check that it already works

Paste this into your agent:

Check my EditorBrain connection. Tell me which workspace is connected and read the instructions for getting started. Do not create projects, upload files or spend credits yet.

What you should see: the agent queries EditorBrain, tells you the correct workspace name and confirms it can read the instructions. If it says it cannot find the tools or that authorization is missing, the connection is not finished. Copying the URL or seeing an authorized account on the web is not enough.

The Copy MCP check button on Connect agents includes your workspace identifier so the agent can verify it. Under the hood it queries workspace_info and get_editing_guide; you do not have to memorize these names.

Start your first video

When the check finishes, write:

I want to edit this video with EditorBrain. Review my preferences and help me get started.

Attach your video if the client can transfer it. If it cannot receive it, the agent will give you a link to upload it to the project. Connecting does not start a render and does not authorize spend. Your preferences, the agent's capabilities and your plan are respected; the agent checks the available tools before it promises an edit.

If something does not work

What happensWhat to do
The agent cannot find EditorBrainTurn the connector on in that chat and reload the agent or open a new chat. Repeat the check.
It asks you to sign in or authorizeFinish MCP connector authorization in the browser. Authorizing the CLI does not authorize MCP.
Another workspace appearsStop and connect the correct workspace before you edit. Do not copy or move projects to fix it.
It cannot read the attached videoAsk it for the project's upload link. You do not need to install the CLI as the automatic fix.
The tool you need is not availableAsk it to check capabilities, the plan and the available alternatives before it promises a render.

Terminal setup (optional)

Only for people who already use their agent's terminal. These commands register the connector; they do not install the EditorBrain CLI.

Codex:

Terminal
codex mcp add editorbrain --url https://api.editorbrain.com/mcp
codex mcp login editorbrain

Claude Code, from your project folder:

Terminal
claude mcp add --transport http --scope project editorbrain https://api.editorbrain.com/mcp

In Claude Code, finish authorization from /mcp. Keep existing connections and check the workspace again. You can also use the CLI and MCP together, with independent authorizations; neither forces you to install the other.

Do I need to install the skills separately?

Not for the MCP path. Connecting an MCP does not install files in the Claude or Codex folders. EditorBrain delivers the instructions through get_editing_guide: they are the same sources as the skill distributed with the CLI, with version, hash and section-by-section reading. The agent reads the instructions it needs for the current step, including Studio; it does not download the whole manual on every message. After a version change it must read the affected guide again.

Local skills are an option for people who also use local tools. A plugin can bundle the connector and the skills, but that is a different install from adding an MCP URL. You do not need to copy manuals into the root of your projects. Availability of local files, a viewer and execution depends on the agent; the instructions do not grant those permissions. Reviews, preferences, budgets and authorizations are also checked in the service operations.

Chat attachments

When the host delivers a compatible attachment and tools/list includes import_project_attachment, the agent can save it in the private project without installing the CLI or Docker. The server receives a temporary reference, verifies the bytes and returns an asset ID and hash; the video is not sent to the model as text. Up to 90 MiB per file, with the workspace storage quota and permissions. The upload does not start renders or spend credits.

The adapter uses openai/fileParams. This does not grant disk access and does not guarantee that every Claude or Codex client transfers attachments. If the host does not offer that transfer or the file is larger, get_project_intake returns the web link of the same project and its available limit. After a timeout, look up get_project_attachment with the same UUID before you retry. Keep preferences and reviews; an upload is not inspection or approval.

Minimum path for an agent

  1. workspace_info, list_brands and list_projects to locate the scope, only if it is not already clear.
  2. check_workflow with projectId for preferences, review, integrations and the effective context.
  3. A real inspection of the material by the agent.
  4. search_from_brief to retrieve references; check their evidence.
  5. Motion, SFX or Studio tools only according to the scenes and permissions you need.
  6. Reviews and feedback with exact IDs and context; check the real result before you deliver it.

Do not load every document or every tool on every scene. Keep valid context and query again when it changes or before a sensitive phase.

Parameters and results

The MCP reference lists names and parameters. mcp-tools.json contains complete schemas for integrators. tools/list in the authenticated session remains the authority on what is available to that user.

The normal /mcp connection keeps its contract with shorter instructions and descriptions. When supported by the service, you can optionally configure https://api.editorbrain.com/mcp?profile=compact to shorten descriptions further. It keeps the same tool names, parameters, results, annotations and permissions; it neither reduces the authorized catalog nor opens private or operator access. Client-side tool search and deferred loading are separate. Catalog size alone does not measure billed token savings.

When advertised, get_tool_guide({name}) returns the full usage contract for one tool available to that connection; includeSchema:true adds its schema. Read it only for an unfamiliar operation, cache by the returned hash, and do not load all tool guides. get_task_guide still routes by task. A cached guide grants no access after revocation. CLI commands and the API stay the same; MCP still needs no local CLI or skill installation.

If your service advertises the workflow profile, connect to https://api.editorbrain.com/mcp?profile=workflow. It groups related operations with typed inputs. For example, call list_projects through find_saved_work({request:{operation:"list_projects",input:{limit:5}}}). Guides retain canonical names: get_tool_guide({name}) returns the correct invocation for this connection. No operation is removed; spending, approval, sharing, deletion and native attachments retain separate tools. Earlier profiles keep their existing callable names and contracts.

When advertised, prepare_edit({projectId}) combines the complete compact workflow and current continuity: preferences, reviews, corrections and jobs. The CLI equivalent is editorbrain workflow prepare --project ID; the API is POST /v1/projects/:id/editing-session. sameAs fields reuse identical values; preserve unavailable sections and pagination. Do not immediately repeat these reads or interpret preparation as spending authorization. If context changes during the read, prepare again before acting. On older versions use compact check_workflow and the continuity you need.

The transport uses HTTP and JSON-RPC. To implement a client, negotiate initialize and use the protocol version the server accepts. Send one operation per request: the server does not accept JSON-RPC batch arrays. Use a compatible MCP SDK instead of assuming every result is plain HTTP JSON.

tools/call can return isError inside the result even when the HTTP transport succeeded. Check both the protocol error and the tool result. Read/write annotations orient the host; authorization is verified again at execution.

Library queries without loading everything

  • list_style_packs returns a summary of packs and techniques, plus the IDs, versions and hashes of sourceStyles. Use sourceId to retrieve only one concrete implementation; detail: "full" includes the recipes and the authorized evidence of the packs. The two inventories are different: a sourceStyles ID is downloaded with get_style_source, not with draft_direction.
  • To explore implementations in small pages, use inventory: "sources", sourceLimit: 6 and continue with sourceAfter: sourcePagination.nextCursor. inventory: "editorial" returns only packs and techniques. A cursor from another version requires you to start over; one page does not represent the whole library.
  • get_reference, get_style_source and get_onboarding_guide accept detail: "summary" to retrieve inventories, pins or preferences without repeating complete documents. They keep their complete responses by default. Follow detailsArguments when you need the script, adaptation rules or options; the summary does not replace the evidence or reading the instructions before you edit.
  • list_authored_scenes recognizes usual mechanism vocabulary in Spanish and English (for example, animated number counter). It is still candidate discovery: check the record and the requirements before you choose. An exact ID, such as lower-third, keeps its exact selection.
  • In list_authored_scenes, keep nextCursor unmodified and repeat the same query, version and filters for the next page. If you change any of them, start without after. An empty result is valid; do not invent a resource.
  • search_sfx respects the project and its configured bank. availability: "selection_required" asks you to choose among the returned banks; "no_banks_available" means none is available. Do not switch banks or generate paid audio automatically.
  • Known errors include recovery.nextStep and product links when they apply. For example, email_verification_required asks you to verify the email, not to buy credits or retry in a loop.

Skills and MCP complement each other

MCP exposes tools and delivers the same canonical skill instructions through get_editing_guide, with no local install. The agent reads SKILL.md and only the guide for the current task. Having a tool registered does not prove the agent read its instructions or reviewed the video.

Continue an earlier edit

This path requires API/MCP 0.45.0 or later. Check availability and the tools of your connection. The agent uses list_projects with query, brandId and updatedSince / updatedBefore dates to find the project; sort: "recent" orders by server activity. Check the workspace first with workspace_info. It must not choose the first ambiguous match. Keep the filters when you continue with nextCursor, deduplicate IDs and restart without a cursor when you change the search. A completed milestone does not hide the project; this contract has no archived-project filter. Then call get_project_continuity before you produce again: it gets the checkpoint, current reviews, pending feedback, jobs and accessible cloud resources. Unavailable sections and incomplete lists stay explicit.

This MCP does not know the private paths of another computer and does not make files appear that were never uploaded. When there is a local CLI 0.45.0 or later, resume ID adds verification of those files. On a cloud agent, recover only the existing authorized resources it needs; respect the storage preference and do not start again a job that is still pending. The read executes nothing and does not authorize spend. Approvals stay in the existing review flow.

Discover by task

If tools/list announces get_task_guide, call it with no arguments to see topics and with topic: "sound" or an ID from its result to read CLI/MCP routes and guides. It also accepts short questions (80 characters maximum), for example topic: "how do I upload a video from my phone": it returns up to three relevant links to guides with an explanation and a video, without loading the whole manual. The agent can share one or two with the user when they help. If the server does not offer the links yet, use the guides, in Spanish or the public index. It is public documentation, not permission or availability of an account. A local CLI operation does not imply its remote execution exists in MCP.

check_workflow.nextActions offers optional, justified suggestions; it is not a required sequence. The current contract accepts detail: "compact", "summary" or "full". Compact keeps the complete editorialSnapshot and avoids identical copies: context.sameAs indicates which fields to read from the snapshot. Full keeps the previous representation; summary only orients and is not a snapshot for editing, approving or spending. Check your connection's schema before you assume a default. To edit, ask for compact directly; summary and context are not two required steps. Reuse documents you already read while their hashes match; pending memory, feedback, permissions and approvals need their current state. Do not repeat resolve_project only to get the same preferences. Read the brief, the direction and the relevant prose that does not appear in the snapshot. Map guides are loaded by task, not all at once.

Available files and tools

MCP works with the media registered on the project and with the attachments the host can transfer. It does not access your computer directly. Use the upload link if the host cannot transfer the video; connecting the service does not install engines or plugins on your machine. The agent checks its capabilities before it produces and keeps the approvals and the evidence of the edit.

Studio artifact

When tools/list announces prepare_review_artifact, the agent can prepare visual Studio with proposals, playback, Changes / Text / AI review, comments by moment, range or point, and My preferences. How it works explains the interaction. The source is the same as the CLI; CLI 0.52.0 also includes that local design; update its skills before you use it. The cloud option gives a private link for the project's existing reviews. The local option uses the agent's file tools and a verified template, without installing EditorBrain.

The artifact does not approve for you and does not send comments automatically: copy your answer into the chat. The edit keeps the existing review mode, preferences, credits and authorizations. If your host does not handle local files, use the web entry and the cloud operations enabled for your plan; connecting MCP does not unlock paid services or tools the server does not offer.

Preferences and memory during review

open_preferences_studio opens the project settings without rendering, uploading material or applying changes. prepare_review_artifact reads preferences from the real context: the client must not inject studio.preferences. A proposal copied from the viewer requires resolving scope and conflicts before you save.

When a real correction arrives, save_editorial_feedback(captureMemory:true) records feedback and a project suggestion. submit_production_review.addresses keeps what the new version corrects. None of these calls confirms a brand memory. Query the context again after you confirm changes. Memory and Studio explain the path.

For usage questions, offer one concrete guide: material, updates or the tutorial found by get_task_guide. Do not dump every schema or manual into the chat to answer a small question.

Next in developersEvery MCP tool →