Solución de problemas

Los mensajes de abajo se citan tal como los escribe el servidor, en inglés; las partes entre ángulos (<action>) varían. La mayoría le llegan al modelo como resultado de una herramienta con isError, así que el asistente puede leer el motivo y a menudo corregir su propia llamada. Los rechazos HTTP y los errores de arranque ocurren antes de que se ejecute ninguna herramienta. Los problemas con la configuración de un cliente concreto (dónde está su log, la forma Docker de una entrada, qué superficie elegir) están en Configuración de clientes.

Cómo leer una llamada fallida

Una llamada que Arcane ha rechazado tiene este aspecto:

container.get failed: arcane: GET /environments/0/containers/web: 404 Not Found: Container not found
Hint: the referenced resource does not exist; use container.list to find valid IDs.

• container.get es la acción, GET /environments/0/containers/web la petición que envió (bajo el /api de Arcane) y 404 Not Found: Container not found el estado de Arcane con su propia explicación.
• La línea Hint es la sugerencia del servidor para el siguiente paso, elegida a partir del estado y de lo que escribió Arcane (más abajo).

Un error sin estado (dial tcp …: connect: connection refused, tls: failed to verify certificate, context deadline exceeded) significa que la petición no llegó a recibir respuesta de Arcane.

El servidor no arranca

Los errores de configuración se escriben en la salida de error estándar y el proceso termina con el estado 2. Los valores que no se pueden leer aparecen juntos:

config: ARCANE_MCP_READ_ONLY="ture" is not on or off (use true/false, 1/0, yes/no or on/off)
ARCANE_MCP_TIMEOUT="60" is not a duration (use a unit: 90s, 5m, 1h30m)

y, cuando todos los valores se leen, cada ajuste que falta y cada combinación que no puede funcionar:

config: ARCANE_URL is required
ARCANE_API_KEY, or ARCANE_USERNAME and ARCANE_PASSWORD, are required in stdio mode

• Un cliente de escritorio suele decir solo que el servidor «no ha podido arrancar» o «se ha desconectado». El mensaje real está en el log MCP del cliente; también puedes ejecutar la misma orden con las mismas variables en un terminal.
• arcane-mcp --help enumera todos los ajustes con sus valores por defecto y termina con el estado 0, tenga lo que tenga el entorno.
• Una combinación se rechaza con un mensaje que nombra los dos ajustes: por ejemplo ARCANE_MCP_HTTP_TOKEN cannot be used with ARCANE_MCP_HTTP_AUTH=apikey: …, ARCANE_URL lists several instances and a stdio server serves one: set ARCANE_MCP_INSTANCE to its name o ARCANE_MCP_HTTP_TLS_CERT and ARCANE_MCP_HTTP_TLS_KEY must be set together. Un certificado y una clave que no se cargan (no existen, no se pueden leer, no forman pareja) también son un error de configuración.
• Un puerto de escucha que no se puede abrir (el puerto está ocupado, la ruta del socket está tomada) se descubre después de la configuración: el servidor registra arcane-mcp stopped con el motivo y termina con el estado 1. Consulta Socket unix.
• Salvo para leer en segundo plano la versión de Arcane (consulta La versión de Arcane y la del catálogo difieren), lo que nunca lo detiene ni lo retrasa, el servidor no contacta con Arcane al arrancar. Un Arcane inalcanzable o una clave errónea aparecen en la primera llamada, no aquí.

Algunos problemas son solo avisos, que se registran al arrancar mientras el servidor sigue adelante: una entrada de ARCANE_MCP_EXCLUDE_TOOLS que no coincide con nada, un LOG_LEVEL obsoleto, un servidor HTTP sin token (HTTP without ARCANE_MCP_HTTP_TOKEN: anyone who reaches the address can use the server, so keep it on a trusted network, que por TCP más allá de loopback y sin ARCANE_MCP_HTTP_ALLOWED_HOSTS añade el riesgo de DNS rebinding), un puerto TCP al que llegan otras máquinas y que sirve HTTP sin cifrar, en cualquier modo de autenticación (the HTTP listener serves plain HTTP on an address other machines can reach, …, salvo que ARCANE_MCP_HTTP_ALLOW_PLAINTEXT esté definida: true lo registra en INFO y false se niega a arrancar) y, por stdio, los ajustes solo HTTP que stdio ignora (stdio mode ignores HTTP-only settings, …, que los nombra).

No se llega a Arcane

container.list failed: arcane: GET /environments/0/containers: Get "http://127.0.0.1:3552/api/environments/0/containers": dial tcp 127.0.0.1:3552: connect: connection refused

ARCANE_URL está mal o no se alcanza desde donde se ejecuta el servidor.

• Dentro de un contenedor, localhost es el propio contenedor: usa el nombre del servicio de Arcane en una red compartida, el nombre del host o host.docker.internal (Docker Desktop).
• El servidor respeta HTTPS_PROXY, HTTP_PROXY y NO_PROXY. Si las tienes definidas para otras herramientas, pon el host de Arcane en NO_PROXY o las peticiones irán al proxy.
• Por HTTP, /readyz responde not ready: arcane is unreachable en la misma situación, y el servidor registra readiness: Arcane health check failed con la causa.
• Una redirección a otro host se rechaza (arcane: refused a redirect to another host: …): ARCANE_URL apunta a algo que envía la petición a otra parte, como una dirección http:// que redirige a https:// o una página de inicio de sesión delante de Arcane. Usa directamente la dirección en la que responde Arcane.

Errores de certificado

container.list failed: arcane: GET /environments/0/containers: Get "https://arcane.lan/api/environments/0/containers": tls: failed to verify certificate: x509: certificate signed by unknown authority

El certificado de Arcane no está firmado por una autoridad en la que confíe el servidor (una CA privada o un certificado autofirmado). Los otros finales habituales son x509: certificate is valid for …, not … (el nombre de ARCANE_URL no está en el certificado) y x509: certificate relies on legacy Common Name field, use SANs instead (el certificado no tiene nombres alternativos del sujeto).

• Confía en la autoridad. En Linux y en la imagen de contenedor, apunta SSL_CERT_FILE a un fichero PEM con el certificado de tu CA (móntalo en el contenedor). En macOS y Windows, añade la CA al almacén de confianza del sistema.
• Corrige el nombre. Usa en ARCANE_URL el nombre de host para el que se emitió el certificado.
• Último recurso: ARCANE_SKIP_TLS_VERIFY=true desactiva la verificación, para todas las instancias. Cualquiera que esté en el camino de red puede entonces leer la clave de API; úsalo solo en una red de confianza.

Arcane no llega a Docker ni al agente

Arcane responde 404, 500, 502 o 503 cuando no llega al demonio de Docker de un entorno o al agente de uno remoto. El servidor reconoce las palabras de Arcane y lo dice, en lugar de dar el recurso por inexistente:

container.get failed: arcane: GET /environments/0/containers/web: 404 Not Found: Failed to retrieve container: failed to connect to Docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Hint: Arcane could not reach the Docker daemon of this environment, so this error does not mean the resource is missing. Check the environment with `environment.test` (it probes the connection) and `environment.get` (its status), and retry once it is reachable.

Para un entorno remoto o edge, la pista empieza por Arcane could not reach this environment's agent (a remote or edge environment that is offline or not connected). Las acciones que sugiere se escriben según la superficie en uso (en meta, arcane_environment con la acción test).

• Entorno local: Arcane ha perdido su socket de Docker (el montaje de /var/run/docker.sock en el contenedor de Arcane, sus permisos, o el propio Docker está parado).
• Entorno remoto o edge: el agente está parado, no llega a Arcane o se emparejó con otra clave. environment.get muestra su estado.
• environment.test cuenta como cambio en la API de Arcane (es un POST), así que el modo de solo lectura lo retiene y la pista nombra solo environment.get; en modo seguro devuelve una vista previa.

401: Arcane ha rechazado la credencial

Un 401 dentro del resultado de una herramienta es la respuesta de Arcane; un 401 a la propia petición HTTP, antes de que se ejecute ninguna herramienta, es la puerta del servidor (consulta Rechazos HTTP). La pista nombra la credencial que llevaba de verdad la petición:

Pista	Credencial que hay que revisar
Hint: Arcane rejected the credentials. Check ARCANE_API_KEY (or ARCANE_USERNAME/ARCANE_PASSWORD).	La del operador: stdio, o un cliente HTTP que no envió clave propia (o envió la del propio servidor) en modo token
Hint: Arcane rejected the API key this client sent in its X-Arcane-API-Key header (the server's ARCANE_API_KEY is not used for it). …	La clave de la cabecera X-Arcane-API-Key del cliente, en modo token
Hint: Arcane rejected the API key this client sent as its Authorization Bearer token (the server's ARCANE_API_KEY is not used for it). …	El Bearer del cliente, en modo apikey
Hint: Arcane refused the apiKey parameter (missing or not valid), which is this action's only credential …	La clave de entorno que se pasó a environment.pair o a notification.dispatch, que nunca envían las credenciales del servidor
Hint: this action does not send the server's credentials (ARCANE_API_KEY is not used); Arcane rejected the credentials passed in its parameters …	Lo que recibió en sus parámetros una ruta pública como auth.login

La clave puede estar mal escrita, revocada, caducada o ser de otra instancia de Arcane. En modo apikey, una clave que recibe 401 de Arcane además se olvida al instante, así que su siguiente petición se vuelve a comprobar y la puerta la rechaza.

Operaciones que necesitan una sesión iniciada

api_key.my_create failed: arcane: this operation accepts only a logged-in session; configure ARCANE_USERNAME and ARCANE_PASSWORD

Arcane solo acepta desde una sesión iniciada unas pocas operaciones de cuenta (passkeys, autenticación multifactor, tus propias claves de API); los flujos de logs y otras acciones WebSocket dicen lo mismo con needs a logged-in session cuando la necesitan. Configura un usuario y una contraseña además de la clave; la sesión se usa solo para esas operaciones.

Por HTTP, el inicio de sesión solo llega a los clientes que actúan como el operador: en modo token, un cliente que no envía clave o que envía la propia ARCANE_API_KEY del servidor. Un cliente con clave propia recibe este error aunque el servidor tenga un inicio de sesión configurado, y en modo apikey, o con varias instancias, lo recibe cualquier cliente. Es intencionado: la cuenta del operador nunca se presta a la clave de otro.

arcane: session login did not complete (mfa_required); an account that requires a second factor cannot be used by this server — use an API key

La cuenta configurada tiene autenticación multifactor. Usa una clave de API en su lugar.

403: a la credencial le falta un permiso

container.list failed: arcane: GET /environments/0/containers: 403 Forbidden: …
Hint: the credential lacks the permission this action needs; an Arcane administrator can grant it through role assignments (role.user_assignments_set).

La clave funciona, pero los roles de su usuario no permiten esta acción en este entorno. O es lo esperado (le diste al asistente un rol reducido a propósito) o un administrador concede el permiso. Las notas de uso de la referencia de herramientas nombran el permiso que necesitan muchas acciones.

404: no encontrado

container.get failed: arcane: GET /environments/0/containers/web: 404 Not Found: Container not found
Hint: the referenced resource does not exist; use container.list to find valid IDs.

• La pista nombra la acción de listado del dominio. Muchos recursos de Arcane se encuentran solo por ID, no por nombre (proyectos, usuarios, registros, claves de API…), así que el asistente tiene que listarlos primero.
• 404 Not Found: Environment not found significa que el environmentId (o ARCANE_ENVIRONMENT_ID) no existe en este Arcane. environment.list da los ID; 0 es el Docker local de Arcane.
• Un 404 cuya explicación dice que no se pudo llegar a Docker o al agente recibe en su lugar la pista de Arcane no llega a Docker ni al agente: el recurso bien puede existir.

Los demás estados (400, 409, 422, 500) llevan la explicación del propio Arcane. Para 400 y 422 el servidor añade los parámetros que acepta y exige la acción y, cuando Arcane nombra los campos que rechazó, una línea por campo con el argumento tal como lo pasaste, el motivo de Arcane y el valor rechazado (nunca el valor de una credencial ni el contenido de un fichero):

volume.create failed: arcane: POST /environments/0/volumes: 422 Unprocessable Entity: validation failed; body.driver: unknown driver
Fields Arcane rejected:
- driver (body.driver): unknown driver (got "nfs")
Required: name. Accepted: driver, driverOpts, environmentId, labels, name.

La versión de Arcane y la del catálogo difieren

level=WARN msg="Arcane version differs from the catalog's major.minor: actions whose routes changed between the two may fail with 404 or 422; use an arcane-mcp release built for this Arcane version" instance=home arcaneVersion=v2.18.0 catalogVersion=v2.17.0

El catálogo se genera a partir de una versión de Arcane, la catalogVersion. Al arrancar, tanto por stdio como por HTTP, el servidor pregunta a cada instancia de Arcane su versión (GET /api/version, una ruta pública, sin credencial) en segundo plano, así que ni la negociación MCP ni el servidor HTTP la esperan. Cuando el major.minor de la instancia difiere del del catálogo, el servidor registra este aviso, una vez por instancia (y de nuevo solo si la instancia informa más tarde de otra versión). Una versión que coincide se registra como Arcane version matches the catalog, y una compilación de desarrollo (next, un commit), como una versión que names no release.

• La diferencia es un aviso y nada más: por HTTP /readyz sigue disponible, y todas las acciones se ejecutan salvo las que se sabe que la versión de la instancia no tiene (consulta Una acción necesita un Arcane más reciente). La mayoría de las rutas no cambian entre versiones menores, y un 503 sacaría de un balanceador un servidor que funciona por un cambio de versión.
• Con ese aviso, un 404 o un 422 puede deberse a una ruta o un campo que cambió entre las dos versiones y no a los argumentos de la llamada. Usa la versión de arcane-mcp hecha para tu versión de Arcane (el registro de cambios la indica), o ejecuta la versión de Arcane a la que apunta el catálogo.
• Por HTTP, /readyz?format=json muestra catalogVersion y versionMatch, nunca la versión exacta, que solo tiene el log (por instancia cuando hay varias; consulta Estado, disponibilidad y parada). Cuando se pide, la versión se vuelve a leer pasados 10 minutos, así que un Arcane actualizado se ve sin reiniciar.
• Una versión que no se puede leer (Arcane caído al arrancar, un proxy que bloquea la ruta) queda desconocida: versionMatch es null, el fallo solo se registra con ARCANE_MCP_LOG_LEVEL=debug y el servidor funciona como siempre.
• Por stdio la versión se lee una vez al arrancar, y de nuevo, cuando tiene más de 10 minutos, antes de una llamada a una acción más reciente que la versión más antigua que cubre el historial del catálogo. Una sesión que termina a los pocos milisegundos de empezar detiene la lectura del arranque, así que puede no registrar el aviso.

Una acción necesita un Arcane más reciente

action "podman.status" is not available: podman.status exists since Arcane v2.17.0; instance "prod" runs v2.16.1. Nothing was sent to Arcane; upgrade Arcane to use it.

El catálogo registra la primera versión de Arcane que sirvió cada acción (a partir de las imágenes oficiales desde la v2.10.0). Una acción que apareció después de la v2.10.0 lleva esa versión: los resultados de find y arcane://tools/{id} la muestran como since, y la referencia de herramientas, como Desde. Antes de llamar a una acción así, el servidor la compara con la versión que leyó de la instancia (la misma lectura que el aviso anterior). Si se sabe que la versión es más antigua, la llamada se rechaza antes de enviar nada a Arcane y antes de pedirte que confirmes una llamada destructiva, con las mismas palabras en todas las superficies; el registro de auditoría anota reason=older_arcane. Actualiza Arcane o llama a otra instancia.

• Antes de rechazar, el servidor vuelve a leer la versión si la que tiene es de hace más de 30 segundos, así que tras una actualización una llamada se rechaza como mucho unos 30 segundos más; reiniciar el servidor lo resuelve al momento. Las demás lecturas de la versión se conservan 10 minutos (el aviso anterior, /readyz).

• Una versión desconocida nunca es motivo de rechazo: una versión que no se pudo leer, una compilación de desarrollo (next, un commit) o una versión preliminar. La llamada llega a Arcane, y si Arcane responde 404 o 405, el error termina con la misma frase como pista: Hint: podman.status exists since Arcane v2.17.0; this Arcane runs next, which names no release. If it is older, the route does not exist there.

• Las acciones presentes en la v2.10.0 nunca se comprueban, ejecute lo que ejecute la instancia: el historial empieza ahí.

• Solo se comprueba si la acción existe. Un parámetro o campo más reciente que la instancia sigue llegando a Arcane, que responde con su propio error.

• Cada instancia se juzga por su propia versión, así que con varias instancias una llamada puede rechazarse en una y ejecutarse en otra.

Llamadas destructivas que no se ejecutan

Sin confirm: true, en un cliente sin elicitación, con ARCANE_MCP_ELICITATION=off o en modo seguro:

volume.delete is destructive (Remove a volume). Nothing was done. Repeat the call with confirm: true once the user has approved it.

Se espera que el modelo te pregunte y repita la llamada con confirm: true. En un cliente con elicitación, el mismo rechazo llega con una nota cuando la pregunta ha fallado: The user was asked to confirm it but did not answer within 5m0s. (ARCANE_MCP_ELICITATION_TIMEOUT) o Asking the user to confirm it failed, so it was not run.

Cuando has respondido a la pregunta:

The user declined to run volume.delete (Remove a volume) when asked to confirm it. Nothing was done. Do not retry it unless the user asks again.

The user dismissed the confirmation of volume.delete (Remove a volume) without answering. Nothing was done; ask the user before trying again.

No son errores: no se ha ejecutado nada porque has dicho que no. Consulta Confirmación de las acciones destructivas.

Falta una acción

Una acción que retiene el modo de solo lectura o una exclusión se responde con el motivo en las superficies dynamic y meta, sea cual sea el nombre que haya usado la llamada:

action "image.prune" is not available: the server runs in read-only mode (ARCANE_MCP_READ_ONLY)

action "image.prune" is not available: excluded by the server configuration (ARCANE_MCP_EXCLUDE_TOOLS)

• En individual, una acción retenida no tiene herramienta, así que el cliente recibe un error de herramienta desconocida y el servidor no escribe registro de auditoría.
• El registro de auditoría de una llamada retenida lleva reason=read_only o reason=excluded y la acción, así que el log te dice qué ajuste la ha quitado.
• Un nombre que no coincide con ninguna acción recibe sugerencias: unknown action "volumes.prune". Did you mean: volume.prune, image.prune, …? Use arcane_find_action to search. En meta, unknown volume action "prunex". Valid actions: …, con lo que el servidor ofrece en ese dominio.

Si falta una acción que esperabas, revisa ARCANE_MCP_READ_ONLY y ARCANE_MCP_EXCLUDE_TOOLS donde se ejecuta el servidor. Algunas llamadas que parecen comprobaciones cambian algo en Arcane y desaparecen en modo de solo lectura: image_update.check_ref y updater.project_check guardan resultados, y environment.test es un POST.

Un cambio «ha salido bien» pero no ha pasado nada

En modo seguro, una llamada que cambiaría algo responde con una vista previa y no envía nada:

## Restart container (container.restart)

- **action**: container.restart
- **executed**: false
- **note**: Safe mode is on (ARCANE_MCP_SAFE_MODE or --safe-mode): this mutating action was not sent to Arcane.
- **params**:
  - **containerId**: web
- **request**: POST /api/environments/0/containers/web/restart
- **safeMode**: true

executed: false es la señal, y el registro de auditoría dice outcome=previewed. Desactiva el modo seguro cuando quieras que los cambios se hagan: reinicia el servidor con ARCANE_MCP_SAFE_MODE sin definir o en false y sin --safe-mode, según cuál de los dos lo activó (una opción de línea de órdenes manda sobre la variable).

Una llamada larga se corta

image.pull did not finish within the action deadline (30m0s, ARCANE_MCP_ACTION_TIMEOUT); it was cancelled. Arcane may still complete work it had already started: check its state before retrying. Cause: …

Las descargas, compilaciones o despliegues grandes pueden durar más que ARCANE_MCP_ACTION_TIMEOUT; súbelo. Una petición normal suelta está limitada en cambio por ARCANE_MCP_TIMEOUT (60s), falla con context deadline exceeded y se registra con reason=request_timeout. Un proxy inverso delante de un servidor HTTP puede tener su propio plazo, más corto: nginx corta una respuesta que pasa 60 segundos sin enviar nada salvo que se suba proxy_read_timeout (consulta Detrás de un proxy inverso).

Una descarga de imagen o un despliegue de proyecto a través de un agente directo que se detiene tras sus primeras líneas con unexpected EOF, mientras el gestor registra Proxied response ended early, es un fallo del proxy de entornos de Arcane v2.17.0 y v2.17.1 con conexiones reutilizadas. arcane-mcp ya no lo esquiva: actualiza Arcane a la v2.17.2, que lo corrige (getarcaneapp/arcane#4592). Esas versiones comparten el major.minor del catálogo, así que ningún aviso de versión las señala.

Rechazos HTTP

Por Streamable HTTP, el transporte rechaza algunas peticiones antes de que se ejecute ninguna herramienta. Cada rechazo es un error JSON-RPC cuyo código es el estado HTTP por −100 (401 → -40100), con "id": null cuando se hizo antes de leer el cuerpo:

{"jsonrpc":"2.0","id":null,"error":{"code":-40100,"message":"unauthorized: send the server's token as Authorization: Bearer <ARCANE_MCP_HTTP_TOKEN>"}}

Estado	Mensaje (comienzo)	Causa y solución
401	unauthorized: send the server's token as Authorization: Bearer <ARCANE_MCP_HTTP_TOKEN>	Modo token: falta la cabecera Authorization o el token es erróneo
401	unauthorized: send your Arcane API key as Authorization: Bearer <key> (this server runs ARCANE_MCP_HTTP_AUTH=apikey)	Modo apikey: no hay token Bearer
401	unauthorized: Arcane does not accept this API key	Modo apikey: Arcane ha rechazado la clave (o es un token de acceso de entorno, que no es la clave de ningún usuario)
400	two different credentials: this server (ARCANE_MCP_HTTP_AUTH=apikey) takes the Arcane API key from Authorization: Bearer; drop X-Arcane-API-Key	Modo apikey con una clave distinta en X-Arcane-API-Key; quita la cabecera
400	no Arcane credential: send your Arcane API key in the X-Arcane-API-Key header	Modo token sin credenciales de operador para esta instancia y sin clave del cliente
400	this server serves several Arcane instances: name one in the X-Arcane-URL header (its name, or its URL as configured)	Varias instancias y ninguna X-Arcane-URL; send one X-Arcane-URL header cuando se repitió
400	Accept must contain both 'application/json' and 'text/event-stream'	Una petición hecha a mano (curl) sin las cabeceras que exige Streamable HTTP
403	X-Arcane-URL names an Arcane instance this server does not serve	La instancia no está en ARCANE_URL; los nombres distinguen mayúsculas. En modo apikey cuenta además como autenticación fallida
403	request refused: the Host is not allowed by this server (see ARCANE_MCP_HTTP_ALLOWED_HOSTS)	El Host que envía el cliente (o el proxy) no está en la lista; añádelo, o haz que el proxy pase el Host del cliente
403	Forbidden: invalid Host header "<host>"	Un servidor en loopback sin ARCANE_MCP_HTTP_ALLOWED_HOSTS al que se llega con un nombre que no es de loopback (un proxy que reenvía el nombre público, o el nombre de un contenedor); define la lista
403	cross-origin request refused: the Origin is not trusted by this server (see ARCANE_MCP_HTTP_TRUSTED_ORIGINS)	Un cliente de navegador en otro origen; añade su origen a la lista
403	this session was opened with another Arcane API key: …	El cliente ha cambiado de clave (o de instancia) a mitad de sesión; envía la misma o inicia una sesión nueva
404	session not found (texto plano)	La sesión ha caducado (ARCANE_MCP_HTTP_SESSION_IDLE_TIMEOUT), el servidor se ha reiniciado o un balanceador ha enviado la petición a otra réplica; los clientes vuelven a inicializar por su cuenta
405	method not allowed: this server runs stateless Streamable HTTP …	El modo sin estado solo atiende POST; el cliente ha intentado abrir un flujo de eventos o borrar una sesión
400	Invalid Request: a message nests JSON deeper than 100 levels	Un mensaje del cuerpo anida objetos y arrays a más de 100 niveles (código JSON-RPC -40000); ningún cliente conocido envía algo así, así que busca un valor construido por error, como una estructura que se contiene a sí misma
413	request body exceeds 16777216 bytes	Un cuerpo mayor que ARCANE_MCP_HTTP_MAX_BODY_BYTES. Un proxy puede rechazar antes cuerpos más pequeños (nginx: client_max_body_size)
429	too many failed authentications from this address or its IPv6 /48 (ARCANE_MCP_HTTP_AUTH_MAX_FAILURES); retry after the time in Retry-After	Demasiados tokens o claves erróneos desde una dirección, o ARCANE_MCP_HTTP_AUTH_NETWORK_FACTOR (10) veces esa cantidad de credenciales rechazadas entre los /64 de un mismo /48 de IPv6 (0 desactiva ese límite). Detrás de un proxy, todos los clientes comparten la dirección del proxy salvo que se defina ARCANE_MCP_HTTP_TRUSTED_PROXIES
429	rate limit: too many requests with this Arcane API key (ARCANE_MCP_HTTP_RATE_LIMIT_RPS); …	El límite de ritmo de la clave; espera lo que indique Retry-After
429	Too many requests for the server card from this address (ARCANE_MCP_HTTP_DISCOVERY_RATE_LIMIT_RPS). Retry later.	Una dirección pidió /server-card o /mcp/server-card más deprisa de lo que permite su cubo; espera lo que indique Retry-After, o guarda la tarjeta en caché (tiene ETag)
503	too many requests in flight …, too many sessions are open …, too many Arcane API keys are in use at once …	Un límite está lleno (ARCANE_MCP_HTTP_MAX_CONCURRENT_REQUESTS, _MAX_SESSIONS, _MAX_API_KEYS); reintenta tras Retry-After o sube el límite
503	could not check the API key with Arcane; retry later	Modo apikey: Arcane no ha respondido con claridad a la comprobación de la clave (inalcanzable, o ha respondido algo que está delante); too many API keys are being checked at once; retry later cuando ya hay 16 comprobaciones en marcha

Los rechazos se registran en warn (HTTP request refused: Host not allowed, … cross-origin, … an Arcane instance this server does not serve, … could not check the API key with Arcane) y las autenticaciones fallidas en info con la dirección del cliente (HTTP request refused: failed authentication addr=… reason=…), así que el log del servidor te dice qué protección respondió y a quién se lo cargó. Si todos los fallos muestran la dirección del proxy, define ARCANE_MCP_HTTP_TRUSTED_PROXIES.

TLS en el propio servidor

• Los clientes no pueden conectarse y el log muestra TLS handshake failed. El campo error dice por qué: client sent an HTTP request to an HTTPS server significa que el cliente usa http://; errores como remote error: tls: bad certificate o local error: tls: bad record MAC suelen indicar que el cliente no confía en el certificado (uno autofirmado, o una cadena sin su intermedio). Estos avisos se limitan a uno por minuto, con suppressed=<n> contando los omitidos, más una línea TLS handshakes failed and were not logged al final de una ráfaga; define ARCANE_MCP_LOG_LEVEL=debug para verlos todos.
• No se sirve un certificado renovado. El servidor recoge los ficheros nuevos en el siguiente handshake (los mira como mucho una vez por segundo) y registra reloaded the TLS certificate. the TLS certificate on disk cannot be loaded; serving the previous one significa que el par nuevo aún no se carga (a medio escribir, clave y certificado de renovaciones distintas); se registra una vez por cada estado de los ficheros. En un contenedor, monta el directorio en lugar de los dos ficheros, o el contenedor seguirá viendo los antiguos.

Socket unix

• serve HTTP: "<path>" exists and is not a socket; refusing to replace it: en ARCANE_MCP_HTTP_ADDR hay un fichero normal o un directorio. Elige otra ruta o bórralo.
• serve HTTP: unix socket "<path>" is already served by another process: otro arcane-mcp (u otra cosa) responde en él. Un socket abandonado por una ejecución que se cayó, en el que no responde nadie, se sustituye con un aviso (removed a stale unix socket left by an earlier run).
• El proxy recibe permission denied (nginx: connect() to unix:… failed (13: Permission denied)). El socket tiene ARCANE_MCP_HTTP_SOCKET_MODE (0660) y pertenece al usuario y al grupo del servidor: ejecuta el servidor con un grupo al que pertenezca el proxy, y comprueba que el proxy puede entrar en el directorio del socket.
• Todos los clientes comparten un cupo de fallos de autenticación. Una conexión por socket no tiene dirección de cliente, así que los fallos se cargan a unix salvo que ARCANE_MCP_HTTP_TRUSTED_PROXIES contenga unix y el proxy rellene ARCANE_MCP_HTTP_TRUSTED_PROXY_HEADER.

Comprobaciones de estado

arcane-mcp --probe (el HEALTHCHECK de la imagen) escribe lo que ha encontrado y termina con 0 si está sano, 1 si no lo está y 2 ante un error de uso:

• arcane-mcp --probe: unhealthy: …: nada ha respondido en la dirección configurada en 3 segundos (--timeout), o ha respondido con otro estado. La sonda lee ARCANE_MCP_HTTP_ADDR y ARCANE_MCP_HTTP_TLS_CERT del mismo entorno y del mismo .env que el servidor; si los cambiaste con opciones en la orden del servidor, pasa las mismas opciones después de --probe.
• the server listens on port 0, chosen by the kernel: …: pasa el puerto que registró el servidor, como --http 127.0.0.1:<port>.
• arcane-mcp --probe: stdio mode (ARCANE_MCP_HTTP_ADDR is not set): …: un contenedor stdio no tiene servidor que sondear y se da por sano mientras se ejecuta.
• Que /readyz (--probe --ready) falle mientras /healthz responde significa que el servidor está en marcha pero no llega a Arcane, o está drenando; la comprobación de vida (/healthz) sigue respondiendo para que no se reinicie el contenedor por culpa de Arcane. Que la versión de Arcane difiera de la del catálogo nunca hace fallar /readyz: consulta La versión de Arcane y la del catálogo difieren.

Problemas con stdio

• Una línea mal formada no termina la sesión. Se responde con un error JSON-RPC (-32700 Parse error, o -32600 Invalid Request: …, por ejemplo para una línea de más de 16 MiB) y la siguiente línea se lee con normalidad.
• Cerrar la entrada estándar no pierde respuestas. El servidor responde a todas las peticiones ya enviadas antes de terminar con el estado 0, así que printf '…' | arcane-mcp recibe también la respuesta de una llamada en curso. La espera está acotada por ARCANE_MCP_ACTION_TIMEOUT; una llamada destructiva que espera una respuesta de elicitación que el cliente ya no puede dar termina tras ARCANE_MCP_ELICITATION_TIMEOUT con el rechazo de confirm: true. Una señal sigue terminando el proceso en 2 segundos como mucho.
• La salida estándar es el protocolo. Nada más puede escribir en ella; un script envoltorio que imprime por stdout rompe la sesión. Los logs del propio servidor van a stderr.
• La forma Docker se queda colgada o termina al instante. Consulta Configuración de clientes: mantén -i y nunca añadas -t ni -d.

Logs

• Dónde: solo en la salida de error estándar. En un servidor stdio es el log MCP del cliente (no el chat); en un contenedor, docker logs.
• Cuánto: ARCANE_MCP_LOG_LEVEL (o --log-level): debug, info (por defecto), warn o error. debug añade detalles como las consultas de autocompletado fallidas, cada handshake TLS fallido y los servidores HTTP recuperados del grupo.
• El registro de auditoría: un registro msg="tool call" por llamada en info (ARCANE_MCP_AUDIT_LOG), con el resultado y el motivo, que muestra si una llamada se rechazó (reason=needs_confirmation, unknown_action, invalid_args, read_only, excluded), se declinó, se quedó en vista previa o falló (status=404, reason=action_deadline). Un nivel por encima de info lo oculta. Consulta Logs y registro de auditoría.

level=INFO msg="tool call" surface=dynamic tool=arcane_execute_action action=volume.delete outcome=refused reason=needs_confirmation duration=246µs
level=INFO msg="tool call" surface=dynamic tool=arcane_execute_action action=image.prune outcome=refused reason=excluded duration=26µs
level=INFO msg="tool call" surface=dynamic tool=arcane_execute_action action=container.list outcome=error duration=524ms status=404

Cuando comuniques un problema, incluye arcane-mcp --version, la versión de Arcane, el transporte, el cliente, el texto del error y las líneas de log correspondientes (no contienen valores de argumentos ni claves).