MCP로 실시간 TUI 공유

이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

상태: 실험적 범위: 공개, 현재 상태 최종 검토: 2026-10-04 담당: AX Code 유지관리자

TUIMCP는 macOS와 Linux의 AX Code TUI를 위한 실험적이고 선택적인 MCP 어댑터입니다. 외부 에이전트가 제한된 인터페이스 상태를 읽고, 사용자가 쓰는 같은 TUI를 탐색할 수 있게 합니다. 이 버전은 Windows를 지원하지 않습니다.

명시적 공유로 TUI를 시작합니다.

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

TUIMCP 막대는 비공개 endpoint.json의 절대 경로를 보여 줍니다. MCP 클라이언트가 다음을 실행하도록 구성합니다.

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

실행 중인 TUI가 보여 주는 경로를 사용합니다. 각 TUI에는 자신의 엔드포인트가 있으며, 자동 검색이나 대상 선택은 없습니다. 클라이언트는 같은 OS 사용자로 실행되어야 합니다. 엔드포인트 파일은 권한 증표로 취급합니다. 비밀 토큰이 들어 있습니다. 커밋하거나, 프롬프트에 복사하거나, 내용을 공유하지 마십시오. 백엔드 자격 증명은 어댑터에 전달되지 않습니다.

도구

get_view_context: 인스턴스와 세대, 리비전, 경로, 선택적 세션 ID, 준비 상태, 탐색이 막혔는지를 반환합니다. 대화 기록, 초안, 세션 제목, 워크스페이스 경로, 자격 증명은 반환하지 않습니다.
select_session: 새 컨텍스트의 ID와 리비전, 프로젝트 세션 ID, 고유 UUID requestId가 필요합니다. TUI의 기존 인증 백엔드 연결을 통해 세션을 검증합니다. 성공 응답은 애플리케이션 경로 상태가 적용되었음을 확인합니다. 렌더링과 세션 로드는 아직 진행 중일 수 있습니다. 세션 ID는 일반적인 AX Code 세션 인터페이스로 따로 얻을 수 있습니다.

초안이나 첨부 파일이 있거나, 모달이나 승인이 대기 중이거나, 세션이 바쁘거나, 백엔드 연결이 끊겼거나, 시작 또는 종료 오버레이가 활성이거나, 사용자가 최근 1.5초 안에 조작한 경우에는 탐색이 거부됩니다. UI나 워크스페이스 상태가 바뀌면 이전 리비전은 무효가 됩니다. 이 도구들은 프롬프트를 제출하거나, 셸 명령을 실행하거나, 권한을 승인하거나, 에이전트 작업을 시작할 수 없습니다.

동일한 requestId를 반복하면 원래 컨텍스트를 포함한 원래 영수증을 반환합니다. 다른 인자로 다시 쓰면 오류입니다. 탐색 요청이 128회가 되면 그 TUI 프로세스의 새 요청은 거부됩니다. 읽기 접근과 기존 영수증은 계속 사용할 수 있습니다. 이 한도를 재설정하려면 명시적 공유로 다시 시작합니다. 영수증은 안전하지 않은 재생으로 밀려나지 않습니다.

deadline_exceeded는 탐색 전에 검증이 취소되었음을 뜻합니다. timeout_unknown 또는 outcome_unknown는 호출자가 확정적인 결과를 받지 못했음을 뜻합니다. 작업이 적용되었을 수 있습니다. 현재 컨텍스트를 읽어 맞춥니다. 어댑터는 자동으로 재시도하지 않습니다. 연결이나 전송이 성공했다는 사실만으로는 탐색이 성공한 것이 아닙니다. isError과 구조화된 결과를 확인합니다.

철회와 수명 주기

TUIMCP 막대에서 **[Revoke]**를 클릭하거나 /tui-mcp-revoke를 실행합니다. 철회는 대기 중인 탐색을 즉시 막고 소켓을 닫습니다. 종료도 엔드포인트를 닫습니다. 다시 시작하면 새 ID와 토큰이 만들어집니다. 크래시한 프로세스는 비활성인 비공개 임시 디렉터리를 남길 수 있습니다. 이전 클라이언트는 그 디렉터리를 통해 새 TUI에 붙을 수 없습니다.

공유는 기본적으로 꺼져 있으며 저장되지 않습니다. 로컬 소유자와 모드 검사는 다른 OS 사용자를 막습니다. TUIMCP는 이미 해당 사용자로 실행 중인 코드에 대한 샌드박스가 아닙니다. 시작 시 소켓 경로가 너무 길다는 보고가 나오면 TMPDIR으로 더 짧은 비공개 임시 루트를 쓰고 새 TUI를 시작합니다.