Preguntas frecuentes

¿Qué superficie de herramientas elijo?

Quédate con la predeterminada, dynamic, salvo que tengas un motivo para cambiarla. Muestra al cliente dos herramientas (arcane_find_action para buscar en el catálogo y arcane_execute_action para ejecutar una acción), ocupa unos 400 tokens de contexto y funciona con cualquier cliente, incluidos los que limitan el número de herramientas.

• Elige meta (52 herramientas, una por dominio, unos 16 k tokens) si tu modelo se maneja mejor con una lista fija que puede leer de antemano.
• Elige individual (461 herramientas, unos 111 k tokens) si quieres que tu cliente apruebe o permita las herramientas una a una. Supera el límite de algunos clientes (VS Code acepta 128 herramientas por petición), así que combínala con ARCANE_MCP_EXCLUDE_TOOLS para recortarla.

Desde las tres se llega a todas las acciones, con los mismos parámetros y las mismas reglas de seguridad; solo cambia la forma de la lista de herramientas. Consulta Superficies de herramientas y, para cada cliente, Configuración de clientes.

¿Cómo me aseguro de que el asistente no pueda cambiar nada?

Usa dos límites, uno en arcane-mcp y otro en Arcane:

1. Arranca el servidor con ARCANE_MCP_READ_ONLY=true (o --read-only). Todas las acciones que cambian algo se quitan antes de que el cliente vea la lista de herramientas, en todas las superficies; una llamada que nombre una de todos modos se rechaza explicando el motivo (en la superficie individual su herramienta no existe). Las lecturas y los recursos siguen funcionando, y también la mayoría de los prompts, sin sus pasos que cambian algo.
2. Dale una clave de API de un usuario de Arcane cuyo rol solo pueda leer. arcane-mcp actúa exactamente con los permisos del usuario de la clave, así que el límite se mantiene aunque el servidor arrancara sin la opción.

Si quieres que el asistente vea las acciones que cambian cosas pero no las ejecute, usa el modo seguro (siguiente pregunta). Consulta Modo de solo lectura.

¿Qué diferencia hay entre el modo de solo lectura y el modo seguro?

• Solo lectura (ARCANE_MCP_READ_ONLY) oculta todas las acciones que cambian el estado. El asistente ni siquiera puede encontrarlas.
• Modo seguro (ARCANE_MCP_SAFE_MODE) las deja a la vista, pero una llamada que cambiaría algo devuelve una vista previa de la petición que habría enviado (método, ruta, cuerpo) y no envía nada. Sirve para probar prompts contra un Arcane en producción o para revisar lo que haría un asistente antes de dejarle hacerlo.

Algunas comprobaciones cambian datos guardados en Arcane aunque parezcan lecturas; image_update.check_ref y updater.project_check, por ejemplo, guardan sus resultados. Cuentan como cambios, así que el modo de solo lectura las oculta y el modo seguro las previsualiza. La referencia de herramientas indica el tipo de cada acción.

¿Qué hace la confirmación de las acciones destructivas?

Una acción que borra o sustituye algo (borrados, purgas, kills, restauraciones, redespliegues, cambios en la definición de un stack) no hace nada hasta que se aprueba, de una de estas dos formas:

• Si tu cliente admite la elicitación MCP, el servidor te pregunta directamente, en la interfaz del cliente, indicando la acción y lo que va a enviar (las credenciales aparecen como (hidden)). Si aceptas, se ejecuta; si rechazas, la respuesta es «no se ha hecho nada» y se le dice al modelo que no lo reintente. Si nadie contesta en cinco minutos (ARCANE_MCP_ELICITATION_TIMEOUT), no se ejecuta nada.
• Si no, la llamada se rechaza con un mensaje que pide al modelo que te pregunte y repita la llamada con confirm: true.

Conviene tener claro de qué protege. Evita accidentes y te mantiene al tanto con un modelo que sigue las instrucciones, pero confirm: true es un argumento que escribe el modelo: uno que lo ponga sin preguntarte se salta la pregunta. Si eso no es aceptable, añade un límite que el modelo no pueda esquivar: la aprobación por herramienta de tu cliente (la superficie individual marca las herramientas destructivas con destructiveHint), el modo seguro, el modo de solo lectura, las exclusiones o un rol de Arcane sin ese permiso. Consulta Confirmación de las acciones destructivas.

¿Puedo usarlo desde otra máquina? ¿Cómo lo hago con seguridad?

Sí. Arráncalo con --http 0.0.0.0:8080 (o ARCANE_MCP_HTTP_ADDR) y los clientes se conectan a /mcp por Streamable HTTP. Antes de exponerlo fuera de una red de confianza:

• Exige autenticación. O bien defines ARCANE_MCP_HTTP_TOKEN, un token bearer compartido que todos los clientes deben enviar (cada usuario puede seguir trayendo su propia clave de Arcane en X-Arcane-API-Key), o bien defines ARCANE_MCP_HTTP_AUTH=apikey, en el que el token bearer es la propia clave de API de Arcane del usuario, verificada contra Arcane. Lo segundo encaja con los conectores remotos y con mcp-remote, que solo pueden enviar una cabecera Authorization. Sin ninguna de las dos, cualquiera que llegue al puerto puede usar el servidor; al arrancar se registra un aviso.
• Cifra. El token bearer y las claves de Arcane viajan en las peticiones. Termina TLS en un proxy inverso, o dale al servidor un certificado con ARCANE_MCP_HTTP_TLS_CERT y ARCANE_MCP_HTTP_TLS_KEY. Un puerto como 0.0.0.0:8080 sin TLS avisa al arrancar de que sirve HTTP sin cifrar a la red: ARCANE_MCP_HTTP_ALLOW_PLAINTEXT=true declara que un proxy cifra ese tramo, y false hace que el servidor se niegue a arrancar en una dirección así (consulta HTTP sin cifrar y el modo endurecido).
• Define ARCANE_MCP_HTTP_ALLOWED_HOSTS con los nombres de host que usan los clientes, contra el DNS rebinding.
• Detrás de un proxy inverso, define ARCANE_MCP_HTTP_TRUSTED_PROXIES y ARCANE_MCP_HTTP_TRUSTED_PROXY_HEADER. Si no, todos los clientes comparten la dirección del proxy y un mismo cupo de autenticaciones fallidas (10 por minuto por defecto), y los errores de un cliente pueden dejar fuera a los demás durante un minuto.
• Si quieres, limita el ritmo de peticiones de cada clave con ARCANE_MCP_HTTP_RATE_LIMIT_RPS.

El modo de solo lectura, el modo seguro y las exclusiones se configuran donde se ejecuta el servidor y se aplican a todos sus usuarios. En Despliegue HTTP tienes recetas con Compose y proxies inversos, y los ajustes están en Modo HTTP y Autenticación HTTP.

¿Puede un servidor gestionar varias instancias de Arcane?

Sí, por HTTP. Enuméralas como ARCANE_URL=home=https://nas.lan:3552,lab=https://lab.example.com; cada petición indica su instancia en la cabecera X-Arcane-URL, y el servidor rechaza cualquier instancia que no hayas listado. Las claves de API pertenecen a un único Arcane, así que ARCANE_API_KEY pasa a llevar una clave por instancia (home=arc_...,lab=arc_...), o bien cada usuario trae la suya.

Por stdio, un servidor sirve una sola instancia: si hay varias listadas, ARCANE_MCP_INSTANCE elige cuál. Para usar dos instancias desde un cliente de escritorio, añade dos entradas, una por instancia.

Varios entornos (hosts de Docker) de un mismo Arcane no necesitan nada de esto: todas las acciones admiten un environmentId, que por defecto vale ARCANE_ENVIRONMENT_ID (0, el Docker local de Arcane), y environment.list da los ID. Consulta Varias instancias.

¿Por qué hay acciones sin probar?

La batería de extremo a extremo ejecuta cada acción en las tres superficies contra instancias reales de Arcane v2.17.2, y 455 de las 461 funcionan. Las otras 6 no pueden funcionar en ese entorno de pruebas:

• Montajes que el entorno de pruebas no puede tener: image.patch necesita un daemon de Docker con el almacén de imágenes de containerd; backup.restore, system.upgrade y system.update_all necesitan que Arcane se ejecute dentro del daemon de Docker que gestiona y, en los dos últimos, que sustituya su propio contenedor, lo que acabaría con la ejecución de las pruebas; system.update_all_status solo responde después de que se haya ejecutado system.update_all.
• Una ruta de compatibilidad obsoleta: job.resolve_run solo funciona con ejecuciones de agentes anteriores a la v2.16.

Siguen en el catálogo porque se ofrecen todas las capacidades de Arcane, y en un montaje en el que Arcane puede hacer el trabajo se comportan como cualquier otra acción. Cobertura e2e cita el motivo completo de cada una.

¿Envía arcane-mcp telemetría?

No. No tiene telemetría, analítica, informes de fallos ni comprobación de actualizaciones, no guarda nada en disco y solo habla con tu cliente MCP y con los servidores de Arcane que configures. Los logs van a la salida de error estándar y nunca contienen los valores de los argumentos. Consulta Privacidad.

¿Qué versiones de Arcane se admiten?

El catálogo se genera a partir de la descripción de la API de Arcane v2.17.2, y todas las pruebas se ejecutan contra la v2.17.2, así que esa es la versión admitida. Arcane v2.16.x no se admite: el catálogo apunta a una sola versión.

Al arrancar, arcane-mcp lee en segundo plano la versión de cada instancia de Arcane y registra un aviso cuando su major.minor difiere del del catálogo; nunca se niega a funcionar (consulta Solución de problemas). Contra otra versión, una acción que Arcane siga sirviendo igual funciona, una cuya ruta o campos hayan cambiado falla con el error del propio Arcane, y lo que Arcane haya añadido después no está hasta que se regenere el catálogo a partir de esa versión. Con un Arcane más antiguo, una acción que esa versión todavía no tiene se rechaza indicando la versión que necesita (podman.status exists since Arcane v2.17.0) en lugar de fallar con un 404 sin más (consulta Una acción necesita un Arcane más reciente). Cada versión de arcane-mcp indica en el registro de cambios la versión de Arcane para la que está hecha.

¿Necesita una clave de API de administrador?

No. Dale la clave de un usuario con el rol más reducido que cubra lo que quieres que haga el asistente. arcane-mcp nunca tiene más derechos que ese usuario: Arcane comprueba los permisos de la clave en cada petición, y un rechazo vuelve con una pista sobre la asignación de rol implicada. Unas pocas operaciones de cuenta (passkeys, autenticación multifactor, crear tus propias claves de API) solo las acepta Arcane desde una sesión iniciada; para ellas hacen falta además ARCANE_USERNAME y ARCANE_PASSWORD.

¿Lo hace el equipo de Arcane?

No. Es un proyecto de código abierto independiente que usa la API pública de Arcane. Los problemas de arcane-mcp se comunican en su repositorio, y los del propio Arcane, a Arcane.