Compartir una TUI en vivo mediante MCP

Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Estado: Experimental Alcance: público, estado actual Última revisión: 2026-10-04 Responsable: mantenedores de AX Code

TUIMCP es un adaptador MCP experimental y optativo para la TUI de AX Code en macOS y Linux. Permite que un agente externo lea un estado acotado de la interfaz y navegue por la misma TUI que estás usando. Windows no se admite en esta versión.

Inicia una TUI con uso compartido explícito:

ax-code --tui-mcp
# Or attach to an existing local backend:
ax-code attach http://localhost:4096 --tui-mcp

La barra TUIMCP muestra la ruta privada absoluta endpoint.json. Configura tu cliente MCP para que arranque:

{
  "mcpServers": {
    "ax-code-tui": {
      "command": "ax-code",
      "args": ["mcp", "tui", "--endpoint", "/absolute/path/from/the/TUI/endpoint.json"]
    }
  }
}

Usa la ruta que muestra tu TUI en ejecución. Cada TUI tiene su propio endpoint; no hay descubrimiento automático ni selección de destino. El cliente debe ejecutarse como el mismo usuario del sistema. Trata el archivo de endpoint como una capacidad: contiene un token secreto. No lo confirmes en el repositorio, no lo copies en prompts ni compartas su contenido. Las credenciales del backend nunca se pasan al adaptador.

Herramientas

get_view_context: devuelve la instancia y la generación, la revisión, la ruta, un ID de sesión opcional, la preparación y si la navegación está bloqueada. No devuelve transcripciones, borradores, títulos de sesión, rutas del espacio de trabajo ni credenciales.
select_session: exige la identidad y la revisión de un contexto reciente, un ID de sesión del proyecto y un UUID único requestId. Valida la sesión mediante la conexión autenticada ya existente de la TUI con el backend. Una respuesta correcta acusa el estado de la ruta de la aplicación; la representación y la carga de la sesión aún pueden estar en curso. Los ID de sesión se pueden obtener aparte mediante las interfaces ordinarias de sesión de AX Code.

La navegación se rechaza mientras existe un borrador o un adjunto, hay un modal o una aprobación pendiente, las sesiones están ocupadas, el backend está desconectado, las superposiciones de arranque o de salida están activas, o el usuario ha interactuado en los últimos 1.5 segundos. Un cambio de la interfaz o del estado del espacio de trabajo invalida las revisiones antiguas. Estas herramientas no pueden enviar prompts, ejecutar comandos de shell, aprobar permisos ni iniciar trabajo del agente.

Un requestId idéntico y repetido devuelve su recibo original, incluido su contexto original. Reutilizarlo con argumentos distintos es un error. Después de 128 solicitudes de navegación, las solicitudes nuevas se rechazan para ese proceso de TUI; el acceso de lectura y los recibos existentes siguen disponibles. Reinicia con uso compartido explícito para restablecer este límite. Los recibos no se expulsan hacia una reproducción insegura.

deadline_exceeded significa que la validación se canceló antes de la navegación. timeout_unknown o outcome_unknown significa que quien llama no recibió un resultado definitivo; la operación podría haberse aplicado. Lee el contexto actual para conciliar. El adaptador nunca reintenta de forma automática. Un éxito de conexión o de transporte por sí solo no significa que una navegación haya tenido éxito; inspecciona isError y el resultado estructurado.

Revocación y ciclo de vida

Haz clic en [Revocar] en la barra TUIMCP o ejecuta /tui-mcp-revoke. La revocación cerca de inmediato la navegación pendiente y cierra el socket. Salir también cierra el endpoint; reiniciar crea una identidad y un token nuevos. Un proceso caído puede dejar un directorio temporal privado inerte; los clientes antiguos no pueden conectar una TUI nueva a través de él.

El uso compartido está desactivado de forma predeterminada y no se persiste. Las comprobaciones locales de propietario y de modo protegen frente a otros usuarios del sistema; TUIMCP no es un sandbox contra código que ya se ejecuta como tu usuario. Si el arranque informa de que la ruta del socket es demasiado larga, usa una raíz temporal privada más corta mediante TMPDIR e inicia una TUI nueva.