# Conectar agentes con MCP

Conecta EditorBrain con Claude o Codex para que tu agente consulte tu marca, tus proyectos y las instrucciones de edición. **No necesitas instalar el CLI ni los skills aparte.**

Elige tu aplicación, conecta tu cuenta y comprueba el acceso. Para instalar el CLI en una carpeta, usa la otra ruta de [Instalar y conectar](https://editorbrain.com/docs/instalar).

## Conectar desde Claude

Estos pasos sirven para Claude en web y escritorio, incluida la pestaña Code. Si usas **Claude Code** en la terminal, usa los comandos de «Configuración por terminal» al final de esta guía.

1. Abre **Conectores** en Claude. Según la versión, puede estar en Configuración o Personalizar.
2. Añade un **conector personalizado / web**. Pon **EditorBrain** como nombre y pega esta URL:

   ```text
   https://api.editorbrain.com/mcp
   ```

3. Guarda la conexión. En la ventana que se abre, inicia sesión en EditorBrain y autoriza el espacio donde están tus proyectos.
4. Vuelve a Claude y activa EditorBrain en los conectores del chat. Si las herramientas no aparecen, abre un chat nuevo.
5. Copia el mensaje de comprobación de abajo.

## Conectar desde Codex

1. Abre la configuración de **servidores MCP** de Codex y añade un servidor.
2. Elige **HTTP / servidor remoto**, usa **EditorBrain** como nombre y pega `https://api.editorbrain.com/mcp`.
3. Guarda y usa **Autenticar / Authenticate** si aparece. Inicia sesión en EditorBrain y autoriza tu espacio.
4. Regresa a Codex; recarga el agente si lo solicita.
5. Copia el mensaje de comprobación de abajo.

Los nombres de los menús pueden variar según la versión del cliente. Si no aparece la opción de conector personalizado, revisa la disponibilidad de tu cuenta o los permisos de tu organización; no es un error de tus proyectos.

## Comprobar que ya funciona

Pega esto en tu agente:

> Comprueba mi conexión con EditorBrain. Dime qué espacio está conectado y lee las instrucciones para empezar. No crees proyectos, subas archivos ni gastes créditos todavía.

**Qué debes ver:** el agente consulta EditorBrain, te dice el nombre del espacio correcto y confirma que puede leer las instrucciones. Si dice que no encuentra las herramientas o que falta autorización, aún no ha terminado la conexión. Copiar la URL o ver una cuenta autorizada en la web no basta.

El botón **Copiar comprobación MCP** de [Conectar agentes](https://editorbrain.com/app/connect) incluye el identificador de tu espacio para que el agente lo verifique. Por dentro consulta `workspace_info` y `get_editing_guide`; no tienes que memorizar estos nombres.

## Empieza tu primer video

Cuando la comprobación termine, escribe:

> Quiero editar este video con EditorBrain. Revisa mis preferencias y ayúdame a empezar.

Adjunta tu video si el cliente permite transferirlo. Si no puede recibirlo, el agente te dará un enlace para subirlo al proyecto. Conectar no inicia un render ni autoriza gasto. Se respetan tus preferencias, las capacidades del agente y tu plan; cuando Render/Storage y el worker están habilitados, puede producir con archivos cloud sin CLI.

## Si algo no funciona

| Qué ocurre | Qué hacer |
| --- | --- |
| El agente no encuentra EditorBrain | Activa el conector en ese chat y recarga el agente o abre un chat nuevo. Repite la comprobación. |
| Pide iniciar sesión o autorizar | Completa la autorización del conector MCP en el navegador. Haber autorizado el CLI no autoriza MCP. |
| Aparece otro espacio | Detente y conecta el espacio correcto antes de editar. No copies ni muevas proyectos para resolverlo. |
| No puede leer el video adjunto | Pídele el enlace de carga del proyecto. No hace falta instalar el CLI como solución automática. |
| La herramienta que necesitas no está disponible | Pide que compruebe las capacidades, el plan y las alternativas disponibles antes de prometer un render. |

## Configuración por terminal (opcional)

Sólo para quien ya usa la terminal de su agente. Estos comandos registran el conector; **no instalan el CLI de EditorBrain**.

Codex:

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

Claude Code, desde la carpeta de tu proyecto:

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

En Claude Code, termina la autorización desde `/mcp`. Conserva las conexiones existentes y vuelve a comprobar el espacio. También puedes usar CLI y MCP juntos, con autorizaciones independientes; ninguno obliga a instalar el otro.

## ¿Necesito instalar los skills aparte?

No para la ruta MCP. Conectar un MCP no instala archivos en las carpetas de
Claude o Codex. EditorBrain entrega las instrucciones a través de
`get_editing_guide`: son las mismas fuentes del skill distribuido con el CLI,
con versión, hash y lectura por secciones. El agente consulta las instrucciones
que necesita para el paso actual, incluido Studio; no descarga todo el manual
en cada mensaje. Tras un cambio de versión debe volver a leer la guía afectada.

Los skills locales son una opción para quien use también herramientas locales.
Un plugin puede agrupar conector y skills, pero es una instalación distinta de
añadir una URL MCP. No necesitas copiar manuales a la raíz de tus proyectos.
La disponibilidad de archivos locales, visor y ejecución depende del agente;
las instrucciones no conceden esos permisos. Las revisiones, preferencias,
presupuestos y autorizaciones se comprueban también en las operaciones del servicio.

## Archivos adjuntos al chat

Cuando el host entrega un adjunto compatible y `tools/list` incluye
`import_project_attachment`, el agente puede guardarlo en el proyecto privado
sin instalar CLI ni Docker. El servidor recibe una referencia temporal, verifica
los bytes y devuelve un asset ID/hash; el video no se envía como texto al modelo.
Hasta 90 MiB por archivo, con cuota de almacenamiento y permisos del espacio.
La subida no inicia renders ni gasta créditos.

El adaptador usa `openai/fileParams`. Esto no otorga acceso al disco ni garantiza
que todos los clientes de Claude/Codex transfieran adjuntos. Si el host no ofrece
esa transferencia o el archivo es mayor, `get_project_intake` devuelve el enlace
web del mismo proyecto y su límite disponible. Tras un timeout, consultar
`get_project_attachment` con el mismo UUID antes de reintentar. Conservar las
preferencias y revisiones; una subida no significa inspección ni aprobación.

## Recorrido mínimo para un agente

1. `workspace_info`, `list_brands` y `list_projects` para ubicar el alcance, solo si aún no está claro.
2. `check_workflow` con `projectId` para preferencias, revisión, integraciones y contexto efectivo.
3. Inspección real del material por el agente.
4. `search_from_brief` para recuperar referencias; consulta sus evidencias.
5. Herramientas de motion, SFX o Studio solo según las escenas y permisos necesarios.
6. Revisiones y feedback con IDs/contexto exactos; comprobar el resultado real antes de entregarlo.

No cargues todos los documentos ni todas las herramientas en cada escena. Conserva contexto válido y vuelve a consultar cuando cambie o antes de una fase sensible.

## Parámetros y resultados

La [referencia MCP](https://editorbrain.com/docs/mcp-tools) lista nombres y parámetros. [mcp-tools.json](/docs/mcp-tools.json) contiene esquemas completos para integradores. `tools/list` en la sesión autenticada sigue siendo la autoridad sobre lo disponible para ese usuario.

El transporte usa HTTP y JSON-RPC. Para implementar un cliente, negocia `initialize` y usa la versión de protocolo aceptada por el servidor. Envía una operación por petición: el servidor no acepta arrays de batch JSON-RPC. Usa un SDK MCP compatible en lugar de asumir que todos los resultados son JSON HTTP plano.

`tools/call` puede devolver `isError` dentro del resultado aunque el transporte HTTP sea exitoso. Comprueba tanto el error de protocolo como el resultado de la herramienta. Las anotaciones de lectura/escritura orientan al host; la autorización se vuelve a verificar al ejecutar.

## Consultas de biblioteca sin cargar todo

- `list_style_packs` devuelve un resumen de packs y técnicas, además de los IDs, versiones y hashes de `sourceStyles`. Usa `sourceId` para recuperar solo una implementación concreta; `detail: "full"` incluye las recetas y la evidencia autorizada de los packs. Los dos inventarios son distintos: un ID de `sourceStyles` se descarga con `get_style_source`, no con `draft_direction`.
- `list_authored_scenes` reconoce vocabulario habitual de mecanismos en español e inglés (por ejemplo, `animated number counter`). Sigue siendo descubrimiento de candidatos: comprueba la ficha y los requisitos antes de elegir. Un ID exacto, como `lower-third`, conserva su selección exacta.
- En `list_authored_scenes`, conserva `nextCursor` sin modificarlo y repite la misma consulta, versión y filtros para la siguiente página. Si cambias cualquiera de ellos, empieza sin `after`. Un resultado vacío es válido; no inventes un recurso.
- `search_sfx` respeta el proyecto y su banco configurado. `availability: "selection_required"` pide elegir entre los bancos devueltos; `"no_banks_available"` indica que no hay ninguno disponible. No cambies de banco ni generes audio de pago automáticamente.
- Los errores conocidos incluyen `recovery.nextStep` y enlaces del producto cuando corresponde. Por ejemplo, `email_verification_required` pide verificar el correo, no comprar créditos ni reintentar en bucle.

## Skills y MCP se complementan

El MCP expone herramientas y entrega las mismas instrucciones canónicas del skill mediante `get_editing_guide`, sin instalación local. El agente consulta SKILL.md, AGENTS.md y sólo las referencias necesarias. Tener una herramienta registrada no demuestra que el agente haya leído sus instrucciones ni revisado el video.

## Continuar una edición anterior

Este recorrido requiere API/MCP **0.45.0 o posterior**. Comprueba su [disponibilidad](https://editorbrain.com/docs/versiones) y las herramientas de tu conexión.
El agente usa
`list_projects` con `query`, `brandId` y fechas `updatedSince`/`updatedBefore`
para encontrar el proyecto; `sort: "recent"` ordena por actividad servidor.
Verifica primero el espacio con `workspace_info`. No debe elegir la primera
coincidencia ambigua. Conserva los filtros al continuar con `nextCursor`, deduplica
IDs y reinicia sin cursor cuando cambies la búsqueda. Un hito completado no oculta
el proyecto; no existe un filtro de proyectos archivados en este contrato.
Después llama `get_project_continuity` antes de producir de nuevo: obtiene
checkpoint, revisiones vigentes, feedback pendiente, trabajos y recursos cloud
accesibles. Secciones no disponibles y listas incompletas permanecen explícitas.

Este MCP no conoce las rutas privadas de otra computadora ni hace aparecer
archivos que nunca se subieron. Cuando hay CLI local 0.45.0 o posterior,
`resume ID` agrega la
verificación de esos archivos. En un agente cloud, recupera solo los recursos
existentes autorizados que necesita; respeta la preferencia de almacenamiento y
no vuelve a iniciar un trabajo que sigue pendiente. La lectura no ejecuta nada
ni autoriza gasto. Las aprobaciones siguen en el flujo de revisión existente.

## Descubrir por tarea

Si `tools/list` anuncia `get_task_guide`, llámala sin argumentos para ver temas y
con `topic: "sonido"` o un ID de su resultado para leer rutas CLI/MCP y guías.
También acepta dudas breves (máximo 80 caracteres), por ejemplo
`topic: "cómo subo un video desde mi celular"`: devuelve hasta tres enlaces
pertinentes a guías con explicación y video, sin cargar todo el manual. El
agente puede compartir uno o dos con el usuario cuando hagan falta. Si el
servidor aún no ofrece los enlaces, usa [las guías](/docs/guias) o el
[índice público](/docs/user-guides.json).
Es documentación pública, no permiso ni disponibilidad de una cuenta. Una
operación local del CLI no implica que exista su ejecución remota en MCP.

`check_workflow.nextActions` ofrece sugerencias opcionales y justificadas; no es
una secuencia obligatoria. `detail: "summary"` pide orientación compacta; omitir
el parámetro o usar `detail: "full"` conserva la respuesta completa. No uses el
resumen como snapshot de ejecución. Reutiliza contexto completo sólo mientras
sigan coincidiendo las versiones editorial y de acceso del miembro.

## Editar usando archivos cloud

Las versiones que anuncian `get_editing_guide` entregan las mismas instrucciones
canónicas del skill, con versión y SHA-256, sin instalar Node.js. El índice indica
qué leer; `SKILL.md`, `AGENTS.md` y `references/cloud-production.md` explican el flujo.

Si tu sesión anuncia `private_render_prepare` y `private_render_submit`, puede
preparar e iniciar renders con archivos que ya subiste al proyecto y código de
escena acotado. Se mantienen las preferencias, revisiones, cotización y autorización
de créditos. El MCP remoto no lee archivos de tu computadora: usa el enlace de
subida del proyecto cuando falte material.

La preparación de audio, copias para revisión y verificación técnica requiere
además la capacidad **media-process-v1** del worker. No está disponible únicamente
por actualizar el CLI; consulta las capacidades de tu cuenta. Estas operaciones
se cotizan por separado y no ejecutan Tempo automáticamente. Una muestra privada
se puede retener y publicar mediante `private_render_publish_review`; publicar no
significa aprobar. Las herramientas locales y proveedores propios siguen siendo
alternativas según las preferencias y el acceso real del agente.


## Edición remota ampliada

Esta ruta requiere las herramientas y operaciones anunciadas por la cuenta; el
código del repositorio o actualizar npm no garantizan que estén desplegadas.

- Sube los crudos al enlace privado del proyecto. El conector no accede al disco.
- `private_render_prepare_media` prepara inspección o cortes y mezcla a partir de
  assets; ejecutar requiere la cotización y autorización habituales. La inspección
  mide metadata real; `private_render_frame` muestra un cuadro por solicitud.
- `private_render_map_words` traslada tiempos medidos por los mismos cortes y
  avisa de palabras atravesadas. `private_render_captions` guarda una capa con el
  preset actual para componerla en la escena; no genera tiempos ni aprueba el video.
- `inspect_source_package` permite leer por páginas la implementación exacta del
  estilo/motion elegido. Conserva acceso por recurso y hashes. La retención de
  archivos y sonidos en el proyecto requiere Cloud Storage y consentimiento.
  Para retomar código propio ya guardado, `get_asset` con `format: "text"` lo lee
  por páginas y comprueba el hash sin descargarlo a tu computadora.
- La muestra usa el mismo visor y las mismas aprobaciones que el flujo local.
  Los chequeos técnicos no sustituyen escuchar y mirar el resultado.

El flujo cloud no ejecuta plugins locales ni programas arbitrarios: Apple Vision,
la creación de archivos Blender y herramientas personales necesitan su entorno
compatible o archivos ya preparados. No cambies a otro proveedor ni descargues a
la computadora sin respetar la preferencia del usuario.

## Artefacto Studio

Cuando `tools/list` anuncia `prepare_review_artifact`, el agente puede preparar
el mismo Studio visual del CLI: propuestas, reproducción, comentarios por tiempo,
Mira/Cambia/Envía y Cómo funciona. La opción cloud da un enlace privado para las
revisiones existentes del proyecto. La local usa las herramientas de archivos del
agente y un template verificado, sin instalar EditorBrain.

El artefacto no aprueba por ti ni envía comentarios automáticamente: copia tu
respuesta al chat. La edición conserva el modo de revisión, preferencias, créditos
y autorizaciones existentes. Si tu host no maneja archivos locales, usa la entrada
web y las operaciones cloud habilitadas para tu plan; conectar MCP no desbloquea
servicios de pago ni herramientas que el servidor no ofrece.