> ## Documentation Index > Fetch the complete documentation index at: https://docs.zas.red/llms.txt > Use this file to discover all available pages before exploring further. # Referencia del agente de Zas: herramientas MCP y errores > Cada herramienta que expone el servidor MCP de Zas, cada código de error, los archivos que escribe en disco y los ajustes que cambian a dónde apunta. Todo lo que expone el servidor MCP `zas-agent`, en una página. | | | | ------------------------- | --------------------------------------------------------------------------- | | Paquete | [`zas-agent`](https://www.npmjs.com/package/zas-agent) en npm | | Nombre en el registro MCP | `io.github.soke1556/zas-agent` | | Transporte | stdio | | Runtime | Node.js 22 o más nuevo | | Código | [github.com/soke1556/zas-agent](https://github.com/soke1556/zas-agent), MIT | ## Comandos ```text theme={null} zas-agent [--profile ] sirve las herramientas MCP por stdio zas-agent pair [--profile ] vincula este agente con una cuenta de Zas [--kind claude_code|codex|other] [--host ] [--no-open] zas-agent telemetry [on|off] dice qué reporta esta máquina, o lo cambia zas-agent --version ``` Sin comando sirve las herramientas MCP, que es para lo que lo arranca un harness. ## Herramientas `channel` toma el nombre o el id de un canal. Un nombre tiene que coincidir con exactamente un canal habilitado. Con un solo permiso, todas las herramientas que toman `channel` lo pueden omitir salvo `zas_list_items` y `zas_get_item`, que siempre nombran el suyo. ### `zas_status` Dice si la máquina está vinculada y lista los canales a los que el agente puede enviar o que puede leer. También imprime la versión del paquete, el perfil y el estado de la telemetría. Sin argumentos. ### `zas_pair` Vincula esta máquina con una cuenta de Zas. La primera llamada devuelve una URL para que abras; una llamada posterior dice si aprobaste. En un perfil ya vinculado, la aprobación reemplaza al agente anterior. | Argumento | Tipo | Notas | | --------- | ---------------- | -------------------------------------------------------------------------------- | | `code` | string, opcional | El código que muestra la página cuando el navegador no pudo llegar a la máquina. | ### `zas_send_file` Envía un archivo de la máquina a un canal habilitado. Devuelve el id del envío, o un id de trabajo cuando la subida tarda más de un minuto. | Argumento | Tipo | Notas | | ----------------- | ----------------- | -------------------------------------------------------------------------------------------- | | `path` | string, requerido | Ruta absoluta o relativa del archivo. | | `channel` | string, opcional | Nombre o id. Opcional con un solo permiso. | | `title` | string, opcional | Etiqueta del envío. Por defecto, el nombre del archivo. | | `expires_in_days` | entero, opcional | Cuántos días enteros vive el envío, mínimo 1. Si se omite, toma la vida normal de la cuenta. | Un canal en modo Directo rechaza esta herramienta con `direct_mode`. Ahí va `zas_send_direct`. Envía cualquier archivo que el proceso pueda leer, secretos incluidos. Mirá [Recomendaciones](/es/agents/recommendations). ### `zas_send_note` Envía una nota: texto plano, o un snippet con su lenguaje. | Argumento | Tipo | Notas | | ----------------- | ----------------- | ---------------------------------------------------- | | `text` | string, requerido | El cuerpo de la nota. | | `channel` | string, opcional | Nombre o id. Opcional con un solo permiso. | | `title` | string, opcional | Etiqueta. Por defecto, la primera línea. | | `lang` | string, opcional | Lenguaje para el resaltado, por ejemplo `ts` o `py`. | | `secret` | boolean, opcional | Tapa el cuerpo hasta que quien lo recibe lo abre. | | `expires_in_days` | entero, opcional | Cuántos días enteros vive el envío, mínimo 1. | ### `expires_in_days` Lo toman las dos herramientas de envío, y solo acorta la vida de un envío. Un pedido más largo del que da el plan se responde con el número del plan en vez de rechazarse, así que pedir 100 días da cinco. El piso es un día entero, porque el anillo cuenta días enteros. Vale la pena para salida que mañana ya está vieja: un log de build, una corrida de tests, la captura de un arreglo. ### `zas_send_direct` Envía un archivo por [Directo](/es/concepts/direct): una transferencia en vivo, de dispositivo a dispositivo, hacia un canal habilitado que está en modo Directo. No se guarda nada. Alguien tiene que tocar **Recibir** en otro dispositivo dentro de diez minutos. La llamada espera un minuto y después devuelve un id de trabajo para consultar con `zas_jobs`. | Argumento | Tipo | Notas | | --------- | ----------------- | ------------------------------------------ | | `path` | string, requerido | Ruta absoluta o relativa del archivo. | | `channel` | string, opcional | Nombre o id. Opcional con un solo permiso. | Un canal que no está en modo Directo rechaza esta herramienta con `not_direct_mode`. ### `zas_receive_direct` Recibe en esta máquina un archivo enviado por Directo. Espera la oferta, la toma y escribe el archivo en disco. Solo para un canal en modo Directo, y solo con un permiso que incluya **lectura**, porque escribe en la máquina. | Argumento | Tipo | Notas | | --------- | ---------------- | -------------------------------------------------------------------------------------------------------- | | `channel` | string, opcional | Nombre o id. Opcional con un solo permiso. | | `dest` | string, opcional | Dónde escribir el archivo. Un directorio significa "adentro". Por defecto, un directorio temporal nuevo. | Nunca pisa un archivo existente. Esperar una oferta solo puede llevar diez minutos, así que la llamada devuelve un id de trabajo después de un minuto. ### `zas_send_direct_fallback` Cuando un trabajo de `zas_send_direct` falló en vuelo, entrega el mismo archivo por la vía confiable. Zas cifra el archivo en esta máquina y guarda solo esa copia cifrada hasta 24 horas; no usa nada de tu espacio, y el dispositivo que ya tomó la oferta la puede bajar después. | Argumento | Tipo | Notas | | --------- | ----------------- | ------------------------------------------------------------ | | `job` | string, requerido | El id de trabajo que reportó el envío por Directo que falló. | Esto deja de ser Directo: los bytes cifrados pasan por almacenamiento. La descripción de la herramienta le dice al modelo que pregunte primero, porque la decisión es tuya. ### `zas_receive_direct_fallback` Cuando un trabajo de `zas_receive_direct` falló en vuelo, baja la copia cifrada que eligió guardar quien enviaba. Funciona solo si esa persona eligió la vía confiable para esa transferencia. El archivo se descifra en esta máquina y se escribe en el mismo destino. | Argumento | Tipo | Notas | | --------- | ----------------- | ---------------------------------------------------- | | `job` | string, requerido | El id de trabajo que reportó la recepción que falló. | ### `zas_list_items` Lista los envíos más recientes de un canal. Necesita un permiso que incluya lectura. | Argumento | Tipo | Notas | | --------- | ----------------- | --------------------------- | | `channel` | string, requerido | Nombre o id. | | `limit` | entero, opcional | De 1 a 50. Por defecto, 20. | ### `zas_get_item` Trae un envío. Una nota vuelve como texto; un archivo se escribe en disco. | Argumento | Tipo | Notas | | --------- | ----------------- | -------------------------------------------------------------------------------------------------------- | | `channel` | string, requerido | Nombre o id. | | `id` | string, requerido | Id del envío, como lo reporta `zas_list_items`. | | `dest` | string, opcional | Dónde escribir el archivo. Un directorio significa "adentro". Por defecto, un directorio temporal nuevo. | Nunca pisa un archivo existente. Un nombre ocupado recibe un sufijo, y la ruta que responde es la que realmente escribió. ### `zas_jobs` Lista los envíos y transferencias por Directo que arrancó este servidor, del más nuevo al más viejo, con la fase que alcanzó cada uno y cómo terminó. Un `job_id` de un envío largo se cobra acá, y un trabajo terminado conserva su resultado. ## Códigos de error El agente responde con un conjunto cerrado. Cualquier cosa que diga una ruta y no esté en este conjunto colapsa a `upload_failed` o `network`, así que nunca llega a una terminal un texto crudo del servidor, ni un stack trace. ### Vinculación e identidad | Código | Qué significa | | ---------------------- | ------------------------------------------------------------------------------ | | `not_paired` | Esta máquina todavía no está vinculada. | | `identity_corrupt` | El archivo de identidad en disco está dañado. | | `agent_revoked` | El dueño revocó este agente. | | `agent_forbidden` | Eso solo lo puede hacer el dueño de la cuenta. | | `pairing_expired` | La vinculación venció. Vinculá de nuevo. | | `pairing_cancelled` | El dueño canceló la vinculación. | | `pairing_not_approved` | Todavía nadie aprobó esta vinculación. | | `pairing_claimed` | Esta vinculación ya fue reclamada. | | `claim_mismatch` | El código no coincide. | | `agent_limit` | La cuenta no admite otro agente. | | `grant_limit` | El plan permite menos canales por agente de los que habilita esta vinculación. | | `feature_disabled` | Los agentes no están habilitados para esta cuenta. | | `sign_in_failed` | Zas no aceptó esta sesión de agente. | | `bad_signature` | Zas rechazó la firma de este agente. Vinculá de nuevo. | | `missing_token` | Falta el token de sesión. Vinculá de nuevo. | ### Canales y permisos | Código | Qué significa | | ----------------- | ------------------------------------------------------- | | `grant_missing` | Este agente no tiene acceso a ese canal. | | `send_forbidden` | Este agente no puede enviar a ese canal. | | `read_forbidden` | Este agente no puede leer ese canal. | | `direct_mode` | Ese canal está en modo Directo. Usá `zas_send_direct`. | | `not_direct_mode` | Ese canal no está en modo Directo. Usá `zas_send_file`. | | `key_stale` | Cambió la clave del canal. Abrí Zas para refrescarla. | ### Envío y lectura | Código | Qué significa | | ---------------- | ----------------------------------------------------------------------------------------------------------- | | `quota_exceeded` | La cuenta llegó a su límite de almacenamiento. | | `rate_limited` | Demasiados envíos seguidos. | | `file_too_big` | El archivo supera el límite del plan. | | `duplicate` | Ese envío ya está en el canal. | | `not_found` | Ese envío no está en el canal. | | `not_yours` | Ese envío no lo hizo este agente. Solo puede cambiar los suyos. | | `stale` | Ese envío cambió mientras este agente trabajaba con él. Leelo de nuevo y reintentá. | | `not_a_note` | Ese envío es un archivo, no una nota. Solo puede cambiar el título; para los bytes está `zas_replace_file`. | | `not_a_file` | Ese envío es una nota, no un archivo. Usá `zas_edit_item`. | | `item_shared` | Ese envío tiene un link público. El dueño quita el link primero. | | `invalid_cap` | Ese archivo ya no está disponible. | | `write_failed` | No se pudo guardar el archivo en el destino. | | `upload_failed` | Falló la subida. | | `oprf_failed` | Zas no respondió bien mientras preparaba el archivo. | ### Directo | Código | Qué significa | | ---------------------- | --------------------------------------------------------------------------------------------------- | | `not_claimed` | Nadie recibió el archivo en diez minutos. Se retiró la oferta. | | `no_offer` | Nadie ofreció un archivo por Directo mientras esta llamada esperaba. | | `offer_taken` | Otro dispositivo recibió ese archivo primero. | | `direct_cancelled` | Cancelaron la oferta del otro lado. | | `direct_failed` | La transferencia por Directo falló en vuelo. Una herramienta de respaldo todavía la puede entregar. | | `direct_not_failed` | Ese trabajo no es una transferencia por Directo que falló en vuelo. | | `file_changed` | El archivo cambió después de la oferta por Directo. Mandalo de nuevo. | | `webrtc_unavailable` | No se pudo cargar el motor WebRTC (`node-datachannel`) en esta máquina. | | `fallback_unavailable` | La vía confiable no está disponible ahora. | ### Lo demás | Código | Qué significa | | ---------- | ----------------------------- | | `network` | No se puede llegar a Zas. | | `internal` | Algo falló dentro del agente. | ## Archivos en disco Un directorio por perfil, así una máquina puede tener un agente de Claude Code y uno de Codex sin que ninguno lea las claves del otro. | Sistema | Ruta | | ------------ | ---------------------------------- | | macOS, Linux | `~/.zas/agent/PERFIL/` | | Windows | `%USERPROFILE%\.zas\agent\PERFIL\` | | Archivo | Qué tiene | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `identity.json` | El uid del agente, el del dueño, el nombre y los dos pares de claves. Guardalo como una clave privada, o borralo y vinculá de nuevo. | | `pending.json` | Una vinculación sin reclamar. Se borra al completar, vencer o cancelar. | | `grants.json` | Un caché de un minuto de los canales del agente y sus claves selladas. El nombre del canal sigue cifrado acá. Descartable. | | `fingerprints.json` | Hashes de lo que produjo un envío idéntico en los últimos diez minutos, para que un reintento responda sin tocar la red. Solo hashes, nunca un título. Descartable. | Un archivo vive un nivel más arriba, en `~/.zas/agent/`, porque es una decisión sobre la máquina y no sobre una identidad: | Archivo | Qué tiene | | --------------- | ------------------------------------------------------------------------------------------- | | `settings.json` | La decisión de telemetría de esta máquina, y si ya se mostró el aviso inicial. Descartable. | Cada archivo se escribe en un temporal y se renombra, así que un corte a mitad de escritura no puede dejar medio archivo. En macOS y Linux el directorio se crea `0700` y cada archivo `0600`. En Windows esos bits no hacen nada: los archivos llevan los permisos del perfil de usuario donde viven, y el paquete no fija otros. Borrar el directorio hace que la máquina se olvide del agente. **No** lo revoca. Eso se hace en **Configuración → Agentes → Revocar**. ## Telemetría El agente reporta el embudo de vinculación y un evento `agent.tool_call` por llamada, para que Zas vea qué herramientas funcionan y cuáles fallan. Viene prendida e imprime un aviso la primera vez. **Lo que nunca manda:** nombres de archivo, títulos, cuerpos de notas, nombres de canal, rutas ni contenido. Tres formas de apagarla, en el orden en que se leen: | Interruptor | Efecto | | ------------------------- | -------------------------------------------------------------------------- | | `ZAS_AGENT_TELEMETRY=off` | Apagada para este proceso. `on` la fuerza prendida. | | `DO_NOT_TRACK=1` | Apagada. El interruptor común entre productos, respetado solo para apagar. | | `zas-agent telemetry off` | Apagada para esta máquina, recordado en `settings.json`. | `zas-agent telemetry` sin valor imprime el estado actual y cuál de los tres lo decidió. `zas_status` imprime la misma línea. ## Ajustes | Ajuste | Por defecto | Qué cambia | | --------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `--profile NOMBRE` | `claude-code` | Qué directorio de identidad usa este proceso. Letras, dígitos, `.`, `_` y `-`, hasta 64, y no puede empezar con punto. | | `--kind` | según el nombre del perfil | El harness que se muestra al aprobar: `claude_code`, `codex` u `other`. | | `--host NOMBRE` | el hostname de la máquina | El host que se muestra al aprobar. | | `--no-open` | apagado | No abrir el navegador al vincular. El link se imprime igual. | | `ZAS_NO_OPEN` | sin valor | Lo mismo que `--no-open`. | | `ZAS_AGENT_HOME` | `~/.zas/agent` | Dónde viven los directorios de perfil. | | `ZAS_AGENT_TELEMETRY` | sin valor | `off` u `on`, para este proceso. | | `DO_NOT_TRACK` | sin valor | `1` apaga la telemetría. | | `ZAS_WEB_BASE` | `https://zas.red` | La app web a la que apunta la URL de vinculación. | | `ZAS_API_BASE` | `https://zas.red/api` | La API. | Solo `--profile`, `ZAS_AGENT_HOME` y los interruptores de telemetría valen la pena a mano. El resto existe para apuntar el paquete a un despliegue de prueba. ## Números | | Valor | | ------------------------------------------------ | ------------------------------------------------------- | | Agentes, plan gratis | 5, revocados incluidos | | Canales por agente, plan gratis | 5, contando los que tuvo alguna vez | | Agentes, sin cuenta | Ninguno | | Agentes por miembro, por defecto en organización | 2, rango 0 a 10 | | Canales por agente, en una organización | Sin tope; el alcance lo gobierna la membresía del canal | | Tope duro, cualquier cuenta | 10 | | Archivo guardado más grande | El límite de tu plan, 50 MB en el gratis | | Archivo más grande que el agente lee | 5 GiB | | Transferencia por Directo más grande | El límite de tu plan, 10 GB en el gratis | | Vida más corta que puede pedir un agente | 1 día | | Vida del token de sesión | 1 hora, se vuelve a firmar solo | | La vinculación espera la aprobación | 10 minutos | | Una vinculación aprobada espera su reclamo | 5 minutos | ## Por dónde seguir Vinculación, comandos del harness y qué hacer si falla. Cada límite que Zas aplica, agentes incluidos. Respuestas cortas a las preguntas de siempre. Buenas costumbres, y la advertencia sobre secretos.