TUI 클라이언트

TUI 클라이언트 (TUI Client)

출처: MCP 공식 문서 — TUI client

TUI는 Inspector의 터미널 인터페이스로, 웹 클라이언트처럼 도구·리소스·프롬프트를 대화형으로 탐색해요. SSH로 원격 호스트에서 쓰거나, 제한된 환경에서 쓰거나, 터미널에 머물고 싶을 때 사용해요.

npx @modelcontextprotocol/inspector --tui node build/index.js   # 임시 stdio 서버와 함께

서버 고르기

CLI와 달리 TUI에는 항목 하나를 고르는 --server <name> 플래그가 없어요. 카탈로그나 설정 파일에서 서버를 읽고, 그 안의 모든 서버를 로드한 뒤 화면 목록에서 고르게 돼요.

mcp-inspector --tui --catalog mcp.json   # 쓰기 가능한 카탈로그, 없으면 빈 상태로 시드(웹 클라이언트와 다름)
mcp-inspector --tui --config mcp.json    # 읽기 전용 세션, 없으면 오류

--catalog도 --config도 없고 임시 대상도 없다면, 기본 쓰기 가능 카탈로그 ~/.mcp-inspector/mcp.json을 사용해요. Configuration and flags 참고.

탭

탭	키	보여주는 것
Info	`i`	서버 정보, capability, 협상된 프로토콜 상세.
Auth	`a`	선택한 서버의 OAuth 상태 + Clear OAuth state 동작.
Resources	`r`	리소스 탐색·읽기.
Prompts	`m`	프롬프트 나열, 인자로 렌더링.
Tools	`t`	도구 보기, 폼 같은 입력으로 실행.
Protocol	`p`	JSON-RPC 요청/응답/알림 기록.
Network	`n`	SSE와 Streamable HTTP 서버의 HTTP 트래픽.
Console	`o`	연결된 stdio 서버 프로세스의 `stderr`.

엑셀러레이터는 첫 글자를 무작정 쓰기보다 충돌을 피해요. Protocol이 p를 쓰니 Prompts가 m을, Console이 o를 쓰는 건 c가 전역 Connect 동작이기 때문이에요.

키	동작
`Left` / `Right` 화살표 또는 `Tab`	탭 전환
`Up` / `Down` 화살표	현재 목록 안에서 이동
`Enter`	항목 선택, 도구 실행, 리소스 가져오기
`c`	선택한 서버에 연결
`d`	연결 끊기
`Esc` 또는 `Ctrl+C`	종료

HTTP 서버 인가

HTTP 또는 SSE 서버를 선택하고 **c**를 눌러 연결해요.
서버가 인가를 요구하면 TUI가 자동으로 OAuth를 시작하고 브라우저에서 인가 URL을 열어요.
브라우저 리다이렉트가 TUI의 루프백 리스너에 도달하면 두 번째 c 없이 연결이 저절로 끝나요.
Auth 탭에서 결과 OAuth 상태를 확인하거나 지울 수 있어요.

TUI의 콜백 리스너는 기본적으로 http://127.0.0.1:6276/oauth/callback이에요. 이 포트는 의도적으로 고정돼 있는데, 사전 등록된(정적) OAuth 클라이언트, Client ID Metadata Document (CIMD), 또는 엔터프라이즈 관리 IdP는 모두 리다이렉트 URI를 미리 알아야 하기 때문이에요. 그 URI를 한 번 등록하면 세션을 넘나들며 동작해요. 브라우저가 다른 머신에 있는 원격 호스트라면 콜백 포트를 포워딩해서 리다이렉트가 이 리스너에 닿게 해야 해요. Callback URLs 참고.

트레이드오프는, 한 번에 하나의 TUI OAuth 흐름만 그 포트를 점유할 수 있다는 거예요. 두 번째 동시 흐름은 EADDRINUSE로 실패해요. --callback-url을 넘기거나 MCP_OAUTH_CALLBACK_URL을 설정해서, 인스턴스마다 다른 고정 포트를 쓰거나, 인가 서버가 리다이렉트 URI를 동적으로 등록한다면 http://127.0.0.1:0/oauth/callback으로 OS가 배정하는 임시 포트를 쓸 수 있어요.

리다이렉트 URI는 등록한 것과 정확히 일치해야 해요. 인가 서버 입장에서 localhost와 127.0.0.1은 다른 URI예요.

카탈로그의 서버별 OAuth 필드(정적 클라이언트 id/secret, 스코프, 엔터프라이즈 관리 플래그)는 자동으로 적용돼요. 설치 단위 설정(CIMD, 엔터프라이즈 IdP)은 ~/.mcp-inspector/storage/client.json에서 오는데, 웹 클라이언트의 Client Settings 대화상자가 쓰는 바로 그 파일이에요. --client-config 또는 MCP_CLIENT_CONFIG_PATH로 다른 파일을 가리킬 수 있어요.

전체 그림은 Authorization에서 볼 수 있어요.

요구사항

TUI는 raw 모드를 지원하는 진짜 TTY가 필요해요. 헤드리스 CI 작업에서는 유용하게 실행되지 않으니 거기선 CLI를 쓰세요.

더 알아보기 (Learn more)

MCP 공식 문서 — TUI client
MCP 공식 문서 — Authorization
MCP 공식 문서 — Configuration and flags

TUI 클라이언트