mcp-ui
무엇인가
mcp-ui는 MCP 서버가 만든 UI 리소스를 MCP 호스트가 렌더링하도록 연결하는 SDK 모음이다. TypeScript 서버·클라이언트 패키지와 Ruby·Python 서버 패키지로 나뉘며, MCP 위에서 동작하는 UI 전달 계층을 담당한다. 이 저장소에서 정리된 패턴은 이후 MCP Apps 사양에 반영됐다.
어떻게 동작하나
서버는 createUIResource로 UI 리소스를 만들고 @modelcontextprotocol/ext-apps/server의 registerAppTool·registerAppResource로 등록한다. 도구는 _meta.ui.resourceUri로 자신의 UI를 가리킨다. 호스트는 이 필드를 감지해 resources/read로 리소스를 가져온 뒤 AppRenderer로 렌더링한다. 리소스의 uri는 ui:// 스킴을 쓰고 mimeType은 text/html;profile=mcp-app이며, 본문은 text 또는 Base64 blob으로 전달된다.
무엇과 다른가
레거시 MCP-UI 방식은 도구 응답 안에 리소스를 직접 넣고 UIResourceRenderer로 그린다. MCP Apps 방식은 도구와 리소스를 resourceUri로 분리해 호스트가 별도로 조회하게 한다. 호스트별 API 차이는 플랫폼 어댑터가 흡수한다. Apps SDK 어댑터는 위젯이 보내는 postMessage를 window.openai 호출로 변환해, 호스트가 사양을 따르지 않아도 같은 위젯 코드가 동작하게 한다.
어떻게 쓰나
설치 후 서버 쪽에서 UI를 반환하는 도구를 정의하고, 클라이언트 쪽에서 AppRenderer에 client, toolName, sandbox, toolInput, toolResult를 넘겨 렌더링한다. 위젯은 postMessage 이벤트로 도구 호출·프롬프트·링크 열기·알림을 요청하고, 호스트는 onUIAction이나 onMessage로 처리한다. 로컬 서버는 ui-inspector로 검사하고, 문서 사이트의 TypeScript·Ruby·Python 워크스루를 따라 기존 서버에 붙일 수 있다.
전제와 한계
렌더링은 호스트 몫이므로 MCP Apps를 지원하지 않는 호스트에서는 레거시 UIResourceRenderer 경로가 필요하다. 지원하는 리소스 타입은 text/html;profile=mcp-app이며, 샌드박스는 프록시 URL 설정을 요구한다. Ruby와 Python 패키지는 UI 리소스 생성만 담당하고 클라이언트 렌더러는 TypeScript 패키지에만 있다.
유사 도구
- CopilotKit에이전트 백엔드와 UI 사이를 잇는 TypeScript 프론트엔드 SDK다. AG-UI 프로토콜로 생성형 UI·공유 상태·휴먼 인 더 루프를 React, Angular, Slack에 연결한다.
- computer-use-linuxMCP 호스트가 리눅스 데스크톱의 접근성 트리·창·스크린샷·입력을 도구로 다루도록 AT-SPI와 Wayland 포털 절차를 주입하는 Claude Code 스킬이다.
- gemini-cliGemini 모델을 터미널에서 직접 쓰는 TypeScript 기반 오픈소스 AI 에이전트다. 파일·셸·검색 도구와 MCP 서버를 붙여 코드 작업을 실행한다.
- mcp-toolboxAI 에이전트와 IDE를 데이터베이스에 직접 연결하는 Go 기반 MCP 서버다. 미리 만들어진 범용 도구와 tools.yaml 기반 커스텀 도구 정의를 함께 제공한다.