Compartilhar uma TUI ao vivo pelo MCP

Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Status: Experimental Escopo: público, estado atual Última revisão: 2026-10-04 Responsável: mantenedores do AX Code

O TUIMCP é um adaptador MCP experimental e opcional da TUI do AX Code no macOS e no Linux. Ele permite que um agente externo leia um estado limitado da interface e navegue a mesma TUI que você está usando. O Windows não tem suporte nesta versão.

Inicie uma TUI com compartilhamento explícito:

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

A barra do TUIMCP mostra o caminho privado absoluto de endpoint.json. Configure o cliente MCP para iniciar:

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

Use o caminho mostrado pela TUI em execução. Cada TUI tem o próprio endpoint; não há descoberta automática nem seleção de destino. O cliente precisa executar como o mesmo usuário do sistema operacional. Trate o arquivo de endpoint como uma capacidade: ele contém um token secreto. Não o envie ao controle de versão, não copie o conteúdo para prompts e não o compartilhe. Credenciais de backend nunca são passadas ao adaptador.

Ferramentas

get_view_context: devolve instância e geração, revisão, rota, ID de sessão opcional, prontidão e se a navegação está bloqueada. Não devolve transcrições, rascunhos, títulos de sessão, caminhos do workspace nem credenciais.
select_session: exige a identidade e a revisão de um contexto recente, um ID de sessão do projeto e um UUID único requestId. Valida a sessão pela conexão autenticada de backend que a TUI já possui. Uma resposta bem-sucedida confirma o estado da rota da aplicação; a renderização e o carregamento da sessão ainda podem estar em andamento. IDs de sessão podem ser obtidos à parte pelas interfaces comuns de sessão do AX Code.

A navegação é rejeitada enquanto existir um rascunho ou um anexo, enquanto um modal ou uma aprovação estiver pendente, enquanto as sessões estiverem ocupadas, enquanto o backend estiver desconectado, enquanto sobreposições de início ou de saída estiverem ativas, ou se o usuário tiver interagido nos últimos 1.5 segundos. Estado alterado da interface ou do workspace invalida revisões antigas. Estas ferramentas não podem enviar prompts, executar comandos de shell, aprovar permissões nem iniciar o trabalho do agente.

Um requestId idêntico e repetido devolve o recibo original, inclusive o contexto original. Reutilizá-lo com argumentos diferentes é um erro. Depois de 128 solicitações de navegação, novas solicitações são recusadas para aquele processo da TUI; o acesso de leitura e os recibos já existentes continuam disponíveis. Reinicie com compartilhamento explícito para repor esse limite. Recibos não são descartados de um modo que permita uma repetição insegura.

deadline_exceeded significa que a validação foi cancelada antes da navegação. timeout_unknown ou outcome_unknown significa que quem chamou não recebeu um desfecho definitivo; a operação pode ter sido aplicada. Leia o contexto atual para reconciliar. O adaptador nunca tenta de novo por conta própria. Sucesso de conexão ou de transporte, isoladamente, não significa que a navegação teve sucesso; inspecione isError e o resultado estruturado.

Revogação e ciclo de vida

Clique em [Revogar] na barra do TUIMCP ou execute /tui-mcp-revoke. A revogação isola na hora a navegação pendente e fecha o soquete. Sair também fecha o endpoint; reiniciar cria uma identidade e um token novos. Um processo que travou pode deixar um diretório temporário privado inerte; clientes antigos não conseguem se anexar a uma TUI nova por meio dele.

O compartilhamento fica desligado por padrão e não é persistido. Checagens locais de dono e de modo protegem contra outros usuários do sistema; o TUIMCP não é um sandbox contra código que já executa como o seu usuário. Se a inicialização informar que o caminho do soquete é longo demais, use uma raiz temporária privada mais curta por meio de TMPDIR e inicie uma TUI nova.