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 #
- Consola → su nombre (arriba a la derecha) → Claves de acceso de IA → Nueva clave. Póngale un nombre que reconozca cuando vaya a revocarla.
- Elija el nivel. El mínimo privilegio que sirva para el objetivo: una clave para un asistente de informes debería ser Solo lectura.
- Copie la clave. Se muestra una vez, al crearla, y nunca más. Si la pierde, revóquela y emita otra.
| Nivel | Permite |
|---|---|
| Solo lectura | Panel, 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 + control | Lectura, y además iniciar y cancelar ejecuciones. |
| Lectura + control + edición | Ademá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 completo | Ademá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 Governance | No 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.
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).
| Herramienta | Nivel | Qué hace |
|---|---|---|
get_dashboard | Lectura | La página principal de la consola en cifras: agentes en línea, tareas, resultados de las últimas 24 h. |
list_jobs, get_job | Lectura | Tareas, con búsqueda y paginación; una tarea completa. |
get_job_runs | Lectura | Historial de ejecuciones de una tarea: estado, tiempos, bytes, el registro de la ejecución, archivos con error. |
list_agents, get_agent | Lectura | Equipos con su estado de conexión, versión, cliente y último contacto. |
get_agent_logs | Lectura | El registro de aplicación del propio agente tal como se envía a la consola; filtro por nivel o por texto. |
list_storage_targets | Lectura | Destinos con su proveedor y el resultado de la última prueba. |
browse_storage_target | Lectura | Listado de carpetas de un destino: nombres, tamaños, fechas. Nunca el contenido de los archivos. |
get_storage_usage | Lectura | Cuá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_usage | Edición | Medir 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_drives | Lectura | Unidades montadas en un agente. |
list_drive_users, list_user_drives | Lectura | Usuarios 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_backup | Lectura | Qué 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_items | Lectura | Buscar elementos por asunto, remitente, destinatario o nombre de archivo, acotados por propietario, carpeta, fecha o adjuntos. |
name_backup_owners | Edición | Completa 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_email | Lectura | Un correo almacenado, descodificado: asunto, remitente, destinatarios, texto del cuerpo y la lista de adjuntos. |
list_metadata_schemas | Lectura | Qué columnas de metadatos se aplican a qué carpetas de un destino, su tipo y cuáles son obligatorias. |
set_metadata_schema | Edición | Definir 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_backups | Lectura | Cada 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_summary | Lectura | Qué 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_usage | Lectura | Llamadas 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_backup | Lectura | Comprobar 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_invoice | Acceso completo | Administradores 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_metadata | Lectura | Las etiquetas de un archivo, su estado de clasificación y las columnas obligatorias que aún faltan. |
query_file_metadata | Lectura | Buscar archivos etiquetados en un destino: por carpeta, por valor de columna o todo lo que aún está pendiente de clasificar. |
set_file_metadata | Edición | Etiquetar un archivo. Sustituye todo su conjunto de valores; las claves de columna desconocidas se rechazan. |
list_archive_rules | Lectura | Las 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_rules | Edición | Marcar 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_rule | Edición | Quitar la regla de una carpeta; a partir de entonces sigue lo que esté marcado por encima, o nada. |
list_vss_instances | Lectura | Lo 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_disks | Lectura | Los 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_customers | Lectura | Los clientes que ve el propietario de la clave. |
list_enrollment_tokens | Lectura | Tokens de registro activos. |
get_customer_health | Lectura | La 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_report | Lectura | El 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_usage | Lectura | Mes 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_agent | Lectura | Listar una carpeta de un equipo, en directo. Solo nombres, tamaños y fechas. |
list_file_versions | Lectura | Versiones anteriores de un archivo en un destino, de la más reciente a la más antigua. |
restore_files | Edición | Restaurar 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_customer | Acceso completo | Añ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_events | Acceso completo | Quién hizo qué y cuándo. Solo administradores de la plataforma. |
get_access_audit | Acceso completo | Quié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_user | Acceso completo | Añ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_status | Acceso completo | Deshabilitar 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_report | Lectura | Los 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_insights | Lectura | Lo 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_jobs | Lectura | Workers del Cloud Agent y lo que están ejecutando. |
run_job, cancel_job | Control | Iniciar una ejecución ahora; cancelar la que está en curso. |
create_job, update_job | Edición | Todas 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_settings | Edición | Nombre descriptivo, límite de tareas simultáneas, límite de subida. |
set_hyperv_rct_mode | Edición | Off / Diag / Compose para las copias incrementales de bloques modificados de Hyper-V en un agente. |
mount_cloud_drive, unmount_cloud_drive | Edición | Añadir o quitar una unidad en un agente. |
assign_user_drive, remove_user_drive | Edición | Dar 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_archive | Edición | Un archivado puntual del buzón y la unidad de una persona: el procedimiento para las personas que se van. |
preview_office365_pst_export | Lectura | Antes 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_export | Edición | Exportar 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_exports | Lectura | Las 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_token | Edición | Anular un token antes de tiempo. |
create_enrollment_token | Acceso completo | Un token de registro para un cliente, con el comando de instalación listo para ejecutar. |
create_storage_target | Acceso completo | Un destino nuevo con sus credenciales. Pase customerTenantId para añadirlo para un cliente en lugar de para usted. |
clone_storage_target | Acceso completo | Un 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_job | Acceso completo | Quitar una tarea y su historial. |
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 ruta | Herramienta |
|---|---|
GET /mcp/dashboard | get_dashboard |
GET /mcp/insights | get_insights |
GET /mcp/customers/{id}/stale-data | get_stale_data_report |
GET /mcp/customers/health, GET /mcp/billing/usage | get_customer_health, get_billing_usage |
GET /mcp/customers/{id}/monthly-report | get_customer_report |
POST /mcp/agents/{id}/files | browse_agent |
GET /mcp/storage-targets/{id}/versions | list_file_versions |
POST /mcp/restore | restore_files |
POST /mcp/customers, GET /mcp/audit, GET /mcp/audit/access | create_customer, get_audit_events, get_access_audit |
GET /mcp/jobs, GET /mcp/jobs/{id}, GET /mcp/jobs/{id}/runs | list_jobs, get_job, get_job_runs |
POST /mcp/jobs, POST /mcp/jobs/{id}/update, POST /mcp/jobs/{id}/delete | create_job, update_job, delete_job |
POST /mcp/jobs/{id}/run, POST /mcp/jobs/{id}/cancel | run_job, cancel_job |
GET /mcp/agents, GET /mcp/agents/{id}, GET /mcp/agents/{id}/logs | list_agents, get_agent, get_agent_logs |
POST /mcp/agents/{id}/settings | update_agent_settings |
GET /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts, POST /mcp/agents/{id}/mounts/{mountId}/delete | list_cloud_drives, mount_cloud_drive, unmount_cloud_drive |
GET /mcp/agents/{id}/vss-instances | list_vss_instances |
GET /mcp/agents/{id}/machine-disks | list_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}/delete | list_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}/clone | list_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}/delete | list_archive_rules, set_archive_rules, remove_archive_rule |
GET /mcp/customers | list_customers |
GET /mcp/enrollment-tokens, POST /mcp/enrollment-tokens, POST /mcp/enrollment-tokens/{id}/revoke | list_enrollment_tokens, create_enrollment_token, revoke_enrollment_token |
POST /mcp/office365/archives, POST /mcp/google-workspace/archives | create_office365_archive, create_google_workspace_archive |
GET /mcp/office365/pst-exports/preview, POST /mcp/office365/pst-exports, GET /mcp/office365/pst-exports | preview_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 #
- Claude — Claude Code, Desktop y claude.ai paso a paso
- VS Code — Copilot en modo agente con la clave en el almacenamiento de secretos
- Automatizar la API con scripts — ejemplos de PowerShell y curl para RMM e informes