CaryvaneAyuda
/
ES

Asistentes de IA y API

Caryvane ofrece un servidor MCP y una API REST equivalente, autenticados con claves de acceso personales. Un asistente con una clave puede responder a «¿qué copias de seguridad fallaron anoche?», ejecutar una tarea, registrar un equipo o configurar el almacenamiento de un cliente, siempre dentro del nivel de la clave y de lo que puede ver el usuario que la emitió.

Crear una clave #

  1. Consola → su nombre (arriba a la derecha) → Claves de acceso de IA → Nueva clave. Póngale un nombre que reconozca cuando vaya a revocarla.
  2. Elija el nivel. El mínimo privilegio que sirva para el objetivo: una clave para un asistente de informes debería ser Solo lectura.
  3. Copie la clave. Se muestra una vez, al crearla, y nunca más. Si la pierde, revóquela y emita otra.
NivelPermite
Solo lecturaPanel, tareas, historial de ejecuciones y registros, agentes y sus registros, destinos de almacenamiento, clientes, tokens de registro, estado de la flota en la nube, lo que el historial de ejecuciones sugiere que va mal, la situación completa de un cliente y los puestos facturables mes a mes. También examinar, tanto un destino como una carpeta de uno de sus equipos, lo que devuelve nombres, tamaños y fechas, nunca el contenido de los archivos.
Lectura + controlLectura, y además iniciar y cancelar ejecuciones.
Lectura + control + ediciónAdemás, crear y editar tareas, iniciar una restauración (siempre en una carpeta nueva, nunca sobre datos en uso), cambiar la configuración de un agente, montar y desmontar unidades en la nube, revocar tokens de registro, crear archivados de Microsoft 365 / Google, exportar a PST un buzón de la copia de seguridad y establecer el modo incremental de Hyper-V de un agente.
Acceso completoAdemás, eliminar tareas, crear destinos de almacenamiento, crear tokens de registro, añadir un cliente y leer el registro de auditoría (solo administradores de la plataforma).
Etiquetas de GovernanceNo es un nivel para asistentes. Solo para Caryvane Governance: enumerar destinos de almacenamiento (nunca con credenciales), examinar carpetas y archivos por nombre, leer columnas de metadatos y etiquetas, leer las reglas de archivado y el resumen del archivado, y establecer valores de etiquetas: un archivo o hasta 500 por llamada, cada uno registrado como sugerencia de Governance con su grado de confianza. Sin tareas, sin ejecuciones, sin restauraciones, sin contenido de archivos y sin ninguna de las herramientas MCP. Las rutas están bajo /governance/, con el mismo encabezado bearer.

Una clave ve exactamente lo que ve su propietario: la clave de un administrador de MSP ve los clientes de ese MSP; la de un usuario de un cliente ve un cliente. Cada acción que realiza una clave se anota en el registro de auditoría con el nombre del propietario. Las claves se revocan en el mismo cuadro de diálogo y dejan de funcionar al instante.

Trate una clave como una contraseña

Quien tenga una clave de acceso completo puede registrar equipos en sus clientes y dirigir las copias de seguridad a su propio almacenamiento. Guarde las claves en el almacén de secretos del propio asistente, nunca en un documento compartido.

Conectar Claude #

El servidor MCP es un único endpoint HTTP, https://console.caryvane.com/mcp/rpc, con la clave como token bearer. En Claude Code, añada lo siguiente a .mcp.json en el proyecto (o a ~/.claude.json para todos los proyectos):

{
  "mcpServers": {
    "caryvane": {
      "type": "http",
      "url": "https://console.caryvane.com/mcp/rpc",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

O desde el terminal: claude mcp add --transport http caryvane https://console.caryvane.com/mcp/rpc --header "Authorization: Bearer <key>". Claude Desktop y claude.ai admiten la misma URL y el mismo encabezado en Configuración → Conectores → Añadir conector personalizado (en inglés, Settings → Connectors → Add custom connector). Tras conectar, pídale que enumere las herramientas; la descripción de cada una está escrita para el asistente, así que sabe que debe consultar list_agents antes de create_job.

Conectar VS Code (Copilot en modo agente) #

Añada lo siguiente a .vscode/mcp.json (VS Code pide la clave una vez y la guarda en su almacenamiento de secretos):

{
  "inputs": [
    { "id": "caryvane-key", "type": "promptString", "password": true, "description": "Caryvane access key" }
  ],
  "servers": {
    "caryvane": {
      "type": "http",
      "url": "https://console.caryvane.com/mcp/rpc",
      "headers": { "Authorization": "Bearer ${input:caryvane-key}" }
    }
  }
}

Las herramientas #

Los nombres son los mismos en MCP y en la API REST de más abajo. El nivel es el nivel mínimo de clave (Lectura = Solo lectura, Control = Lectura + control, Edición = Lectura + control + edición).

HerramientaNivelQué hace
get_dashboardLecturaLa página principal de la consola en cifras: agentes en línea, tareas, resultados de las últimas 24 h.
list_jobs, get_jobLecturaTareas, con búsqueda y paginación; una tarea completa.
get_job_runsLecturaHistorial de ejecuciones de una tarea: estado, tiempos, bytes, el registro de la ejecución, archivos con error.
list_agents, get_agentLecturaEquipos con su estado de conexión, versión, cliente y último contacto.
get_agent_logsLecturaEl registro de aplicación del propio agente tal como se envía a la consola; filtro por nivel o por texto.
list_storage_targetsLecturaDestinos con su proveedor y el resultado de la última prueba.
browse_storage_targetLecturaListado de carpetas de un destino: nombres, tamaños, fechas. Nunca el contenido de los archivos.
get_storage_usageLecturaCuánto hay almacenado en cada destino, con la fecha de la medición. Se toma de la pasada nocturna; un destino sin cifra se indica como tal, nunca como cero.
measure_storage_usageEdiciónMedir un destino ahora en lugar de usar la cifra de anoche. Es lento y, en un proveedor que cobra por uso, tiene coste.
list_cloud_drivesLecturaUnidades montadas en un agente.
list_drive_users, list_user_drivesLecturaUsuarios de unidad (las personas que inician sesión en sus propias unidades desde sus ordenadores y teléfonos) y las unidades que tiene cada uno.
browse_backupLecturaQué contiene una copia de seguridad, nivel a nivel: tipo, después de quién es el buzón o la unidad, después las carpetas. Responde a «¿de quién es este OneDrive?».
search_backup_itemsLecturaBuscar elementos por asunto, remitente, destinatario o nombre de archivo, acotados por propietario, carpeta, fecha o adjuntos.
name_backup_ownersEdiciónCompleta de qué buzón, unidad o sitio procede cada elemento catalogado y pone nombre a esos ID. Se ejecuta una vez por tarea tras actualizar; solo rellena huecos.
read_backup_emailLecturaUn correo almacenado, descodificado: asunto, remitente, destinatarios, texto del cuerpo y la lista de adjuntos.
list_metadata_schemasLecturaQué columnas de metadatos se aplican a qué carpetas de un destino, su tipo y cuáles son obligatorias.
set_metadata_schemaEdiciónDefinir las columnas que pueden llevar los archivos de una carpeta, creando el conjunto o sustituyéndolo; una ruta de carpeta vacía significa la raíz del contenedor, y las columnas se heredan hacia abajo en el árbol. Consulte antes list_metadata_schemas: esto sustituye las columnas de la carpeta.
list_xero_backupsLecturaCada organización de Xero que ve la clave, cliente por cliente: conectada o pendiente de que el cliente vuelva a iniciar sesión en Xero, dónde se guarda la copia, si ha terminado la primera copia de seguridad y cómo fue la última ejecución. Es el punto de partida para «¿está Xero copiado?».
get_xero_backup_summaryLecturaQué contiene la copia de seguridad de una organización (recuentos por tipo de registro y adjuntos), a fecha de hoy o de cualquier fecha pasada.
get_xero_backup_usageLecturaLlamadas a la API de Xero y bytes descargados en este mes natural frente a la cuota, por organización o para cada cuenta facturada que ve la clave.
verify_xero_backupLecturaComprobar una copia de seguridad frente al balance de sumas y saldos de Xero: las cuentas por cobrar y por pagar, reconstruidas a partir de las facturas, notas de crédito y pagos en exceso copiados, deben coincidir con él. No hace llamadas a Xero.
preview_xero_backup_invoiceAcceso completoAdministradores de la plataforma: cómo sería la factura de la copia de seguridad de Xero de un cliente para un mes natural (organizaciones, datos usados e incluidos, exceso, total). No guarda ni envía nada.
get_file_metadataLecturaLas etiquetas de un archivo, su estado de clasificación y las columnas obligatorias que aún faltan.
query_file_metadataLecturaBuscar archivos etiquetados en un destino: por carpeta, por valor de columna o todo lo que aún está pendiente de clasificar.
set_file_metadataEdiciónEtiquetar un archivo. Sustituye todo su conjunto de valores; las claves de columna desconocidas se rechazan.
list_archive_rulesLecturaLas reglas de archivado de un destino: qué carpetas están marcadas, qué antigüedad debe tener un archivo y si el archivado está activado para ese destino.
set_archive_rulesEdiciónMarcar carpetas para archivado, muchas a la vez con la misma regla, que es la forma real de una petición como «archivar de la 5445 a la 5460 al cabo de un año». La respuesta enumera las reglas tal como se guardaron y las carpetas rechazadas. Las reglas no hacen nada hasta que se ejecuta una tarea de archivado.
remove_archive_ruleEdiciónQuitar la regla de una carpeta; a partir de entonces sigue lo que esté marcado por encima, o nada.
list_vss_instancesLecturaLo que un agente de Windows puede copiar de forma coherente con la aplicación: máquinas virtuales de Hyper-V, bases de datos SQL, AD. En directo desde el equipo.
list_machine_disksLecturaLos discos de un agente de Windows: número, tamaño, tipo, letras de unidad y si se pueden copiar como imagen. En directo desde el equipo.
list_customersLecturaLos clientes que ve el propietario de la clave.
list_enrollment_tokensLecturaTokens de registro activos.
get_customer_healthLecturaLa situación completa de un cliente para una incidencia: equipos que no contactan, tareas cuya última ejecución terminó con error o advertencia, tareas que nunca se ejecutaron, destinos que perdieron su inicio de sesión.
get_customer_reportLecturaEl informe mensual de un cliente en cifras, nunca el correo: el informe archivado tal como se envió, o generado en el momento. «Sin medir» no es cero. Con includePdf también devuelve el PDF con su marca.
get_billing_usageLecturaMes a mes y por cliente: equipos a fin de mes, créditos en la nube y GB usados, importe facturado y si se pagó. El mes en curso es un total acumulado, no una factura.
browse_agentLecturaListar una carpeta de un equipo, en directo. Solo nombres, tamaños y fechas.
list_file_versionsLecturaVersiones anteriores de un archivo en un destino, de la más reciente a la más antigua.
restore_filesEdiciónRestaurar desde una copia de seguridad en el equipo que la hizo. Siempre en una carpeta nueva con marca de tiempo: nunca puede escribir sobre datos en uso.
create_customerAcceso completoAñadir una cuenta en cualquier punto de su propio árbol: un cliente o, para un distribuidor, un MSP por debajo de él. Pase parentTenantId y tenantType; el servidor rechaza las combinaciones que la cuenta superior no puede tener.
get_audit_eventsAcceso completoQuién hizo qué y cuándo. Solo administradores de la plataforma.
get_access_auditAcceso completoQuién restauró, descargó, previsualizó, examinó o eliminó qué, para los clientes que ve su clave, filtrado por cliente, periodo, tipo de acción y persona. Consulte el informe de accesos.
add_drive_userAcceso completoAñadir a un cliente un usuario de unidad que inicia sesión con Microsoft, Google o una contraseña. Si el cliente ha conectado Microsoft 365 o Google Workspace, la persona debe ser allí un miembro habilitado (no un invitado), y su cuenta se vincula para que nadie de otra organización pueda iniciar sesión en su nombre.
set_drive_user_statusAcceso completoDeshabilitar un usuario de unidad (una persona que se va, un teléfono perdido) o volver a habilitarlo. Todos sus dispositivos cierran sesión en su siguiente petición.
get_stale_data_reportLecturaLos datos obsoletos y huérfanos de un cliente: archivos sin modificar en N años, buzones y unidades de personas que se han ido y lo que podría pasar al archivado, con borradores de reglas de archivado que nunca aplica. Consulte el informe de datos obsoletos.
get_insightsLecturaLo que sugiere el historial de ejecuciones: tareas que fallan más a menudo que antes, cuánto mueve cada una frente al mes anterior y cuáles siguen acumulando historial.
get_cloud_fleet, get_cloud_worker_jobsLecturaWorkers del Cloud Agent y lo que están ejecutando.
run_job, cancel_jobControlIniciar una ejecución ahora; cancelar la que está en curso.
create_job, update_jobEdiciónTodas las opciones del asistente de la consola: archivos, de almacenamiento a almacenamiento, conector, coherente con la aplicación, en la nube o en un agente, programación, retención.
update_agent_settingsEdiciónNombre descriptivo, límite de tareas simultáneas, límite de subida.
set_hyperv_rct_modeEdiciónOff / Diag / Compose para las copias incrementales de bloques modificados de Hyper-V en un agente.
mount_cloud_drive, unmount_cloud_driveEdiciónAñadir o quitar una unidad en un agente.
assign_user_drive, remove_user_driveEdiciónDar una unidad en la nube a un usuario de unidad, o quitársela. Le sigue a cada ordenador y teléfono en el que inicie sesión. Los archivos del almacenamiento nunca se tocan.
create_office365_archive, create_google_workspace_archiveEdiciónUn archivado puntual del buzón y la unidad de una persona: el procedimiento para las personas que se van.
preview_office365_pst_exportLecturaAntes de una exportación: cuántos mensajes abarca una selección y aproximadamente cuánto ocupan, solo a partir del catálogo de la copia de seguridad. Un buzón, opcionalmente una carpeta (con o sin sus subcarpetas) y todo el correo, solo el correo de más de N días o un intervalo de fechas. No se lee nada del almacenamiento; los mensajes catalogados sin tamaño hacen que el total sea una estimación a la baja.
create_office365_pst_exportEdiciónExportar a archivos PST el correo que una copia de seguridad de Microsoft 365 ya contiene, dividido en partes de unos 3 GB, con un informe al lado que nombra cada mensaje que ha quedado fuera. La misma selección que la vista previa; los archivos van a una carpeta de uno de los agentes del cliente o a un destino de almacenamiento, y lo ejecuta el agente propietario de la copia de seguridad, otro agente del cliente o la nube de Caryvane (un crédito en la nube; solo a un destino de almacenamiento). La copia de seguridad solo se lee. No disponible en el periodo de prueba. Consulte Exportar a PST.
list_office365_pst_exportsLecturaLas exportaciones solicitadas hasta ahora y cómo terminó cada una: mensajes escritos, omitidos y fallidos, cuántos archivos PST hay y dónde están ellos y el informe. Opcionalmente, de una sola tarea de copia de seguridad.
revoke_enrollment_tokenEdiciónAnular un token antes de tiempo.
create_enrollment_tokenAcceso completoUn token de registro para un cliente, con el comando de instalación listo para ejecutar.
create_storage_targetAcceso completoUn destino nuevo con sus credenciales. Pase customerTenantId para añadirlo para un cliente en lugar de para usted.
clone_storage_targetAcceso completoUn destino nuevo que reutiliza las credenciales de uno existente sin que nadie manipule las claves: se quedan en el servidor. Elija un bucket nuevo (creado opcionalmente con Object Lock) y el historial de versiones; la inmutabilidad nunca se copia. No sirve para almacenamiento conectado mediante inicio de sesión.
delete_jobAcceso completoQuitar una tarea y su historial.
Revendedores

Cuando el propietario de la clave ve varios clientes, las herramientas que crean cosas necesitan un cliente: create_job lo deduce del agente, o necesita customerTenantId para una tarea del Cloud Agent; create_enrollment_token recibe tenantId. No se puede crear nada que cruce la frontera entre clientes: una tarea no puede leer el almacenamiento de un cliente y escribir en el de otro.

La API REST #

Las mismas operaciones como JSON sencillo sobre HTTPS, para scripts, integraciones con el RMM y cualquier asistente que hable HTTP en lugar de MCP. La misma clave y el mismo encabezado: Authorization: Bearer <key>. Las respuestas son JSON; los errores son códigos de estado estándar con un mensaje.

curl -s https://console.caryvane.com/mcp/jobs?take=50 \
  -H "Authorization: Bearer <key>"

curl -s -X POST https://console.caryvane.com/mcp/jobs/14/run \
  -H "Authorization: Bearer <key>"
Método y rutaHerramienta
GET /mcp/dashboardget_dashboard
GET /mcp/insightsget_insights
GET /mcp/customers/{id}/stale-dataget_stale_data_report
GET /mcp/customers/health, GET /mcp/billing/usageget_customer_health, get_billing_usage
GET /mcp/customers/{id}/monthly-reportget_customer_report
POST /mcp/agents/{id}/filesbrowse_agent
GET /mcp/storage-targets/{id}/versionslist_file_versions
POST /mcp/restorerestore_files
POST /mcp/customers, GET /mcp/audit, GET /mcp/audit/accesscreate_customer, get_audit_events, get_access_audit
GET /mcp/jobs, GET /mcp/jobs/{id}, GET /mcp/jobs/{id}/runslist_jobs, get_job, get_job_runs
POST /mcp/jobs, POST /mcp/jobs/{id}/update, POST /mcp/jobs/{id}/deletecreate_job, update_job, delete_job
POST /mcp/jobs/{id}/run, POST /mcp/jobs/{id}/cancelrun_job, cancel_job
GET /mcp/agents, GET /mcp/agents/{id}, GET /mcp/agents/{id}/logslist_agents, get_agent, get_agent_logs
POST /mcp/agents/{id}/settingsupdate_agent_settings
GET /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts/{mountId}/deletelist_cloud_drives, mount_cloud_drive, unmount_cloud_drive
GET /mcp/agents/{id}/vss-instanceslist_vss_instances
GET /mcp/agents/{id}/machine-diskslist_machine_disks
GET /mcp/drive-users, POST /mcp/drive-users, PATCH /mcp/drive-users/{id}list_drive_users, add_drive_user, set_drive_user_status
GET /mcp/drive-users/{id}/drives, POST /mcp/drive-users/{id}/drives, POST /mcp/drive-users/{id}/drives/{driveId}/deletelist_user_drives, assign_user_drive, remove_user_drive
GET /mcp/storage-targets, POST /mcp/storage-targets, GET /mcp/storage-targets/{id}/browse, GET /mcp/storage-targets/usage, POST /mcp/storage-targets/{id}/measure-usage, POST /mcp/storage-targets/{id}/clonelist_storage_targets, create_storage_target, clone_storage_target, browse_storage_target, get_storage_usage, measure_storage_usage
GET /mcp/storage-targets/{id}/archive-rules, POST /mcp/storage-targets/{id}/archive-rules, POST /mcp/storage-targets/{id}/archive-rules/{ruleId}/deletelist_archive_rules, set_archive_rules, remove_archive_rule
GET /mcp/customerslist_customers
GET /mcp/enrollment-tokens, POST /mcp/enrollment-tokens, POST /mcp/enrollment-tokens/{id}/revokelist_enrollment_tokens, create_enrollment_token, revoke_enrollment_token
POST /mcp/office365/archives, POST /mcp/google-workspace/archivescreate_office365_archive, create_google_workspace_archive
GET /mcp/office365/pst-exports/preview, POST /mcp/office365/pst-exports, GET /mcp/office365/pst-exportspreview_office365_pst_export, create_office365_pst_export, list_office365_pst_exports

Los parámetros son los argumentos de la herramienta en JSON en el cuerpo (POST) o en la cadena de consulta (GET). Las descripciones de las herramientas MCP, que ve el asistente, son la referencia de campos que manda; un documento OpenAPI para crear una Action de un GPT personalizado de ChatGPT está previsto, pero aún no se ha publicado.

Lo que un asistente no puede hacer #

Por diseño, no hay ninguna herramienta que descargue el contenido de un archivo, que elimine archivos del almacenamiento ni que los mueva. Examinar devuelve solo metadatos, tanto si es un destino como una carpeta de uno de sus equipos.

Un asistente puede iniciar una restauración, y dos cosas limitan lo que eso significa. Los archivos van de su almacenamiento a su equipo sin pasar por el asistente ni por nosotros: el agente los obtiene directamente de su almacenamiento. Y una restauración nunca puede escribir sobre lo que ya existe: siempre acaba en una carpeta nueva con marca de tiempo dentro de la carpeta que usted indique, así que la copia con la que iba a comparar sigue donde la dejó. Devolver algo a su sitio es decisión de una persona. Cada restauración es una tarea, así que aparece en la lista de tareas y en su historial de ejecuciones como cualquier otra.

La única operación que elimina datos, una tarea de archivado con la eliminación en el origen activada, se crea como cualquier otra tarea, con esa opción desactivada salvo que se active expresamente, y cada archivo que elimina se anota antes en el catálogo.

read_backup_email es el único punto en el que un asistente ve el interior de algo, así que conviene ser preciso sobre lo que significa. Lee un mensaje del que usted ya nos pidió hacer copia de seguridad, descodificado a partir de la copia de su propio almacenamiento, y solo cuando se pide ese elemento concreto por su ID. No es una búsqueda en el cuerpo de los mensajes: search_backup_items busca en asuntos, remitentes, destinatarios y nombres de archivo, nunca en el texto del cuerpo. Nada indexa el contenido de su correo.

El etiquetado merece una nota aparte, porque parece inofensivo y no lo es del todo. set_file_metadata sustituye todo el conjunto de valores de un archivo en lugar de combinarlo, así que todo lo que omita se elimina: lea antes el archivo si solo quiere cambiar una columna. Además, una regla de archivado puede depender de una etiqueta, de modo que cambiarla puede cambiar si un archivo acaba archivándose. Aun así, nunca puede hacer que se archive un archivo que no tuviera ya la antigüedad suficiente y no estuviera ya cubierto por una regla: una condición solo restringe.

Los metadatos nunca se leen del interior de sus archivos. Son lo que alguien escribió, o lo que llegó desde SharePoint, Egnyte o Google Drive: no abrimos un documento para decidir de qué trata.

Para profundizar #