MCP Apps 구현 중 발견한 구조적 URI 바인딩 및 CSS 우선순위 결함 해결

Two undocumented bugs in MCP Apps I found building a task panel for Claude

Adeolu Adesina2026년 6월 22일5분intermediate

AI 요약

Context

Claude 내 persistent task panel 구현을 위한 MCP Apps(SEP-1865) 기반 서버 설계 과정에서 발생한 런타임 이슈 분석. 프레임워크의 추상화 계층으로 인한 메타데이터 유실 및 Sandbox 환경의 제약 사항으로 인한 UI/UX 동작 불능 상태 직면.

Technical Solution

Parameterized Resource Template 대신 Static Resource(ui://wingman/panel)를 등록하여 호스트의 prefetch 및 rendering 보장
FastMCP의 dict 자동 직렬화로 인한 _meta 필드의 structuredContent 내부 중첩 문제를 해결하기 위해 CallToolResult 객체 직접 반환 구조로 변경
호스트가 CallToolResult 최상위 _meta에서 resourceUri를 읽도록 강제하여 iframe 바인딩 정상화
User-Agent 스타일시트의 [hidden] 속성보다 우선순위가 높은 .class 기반 display: flex 충돌을 해결하기 위해 !important를 적용한 CSS override 수행
iframe Sandbox 제약으로 인해 작동하지 않는 confirm(), navigator.clipboard, Blob API를 sendMessage 기반의 메시지 라우팅 구조로 대체

실천 포인트

- 프레임워크 사용 시 반환값이 내부적으로 어떻게 직렬화되어 전송되는지 Wire format 수준에서 검증 - UI 상태 제어를 위해 `hidden` 속성 사용 시, CSS Specificity에 의해 덮어쓰여지지 않았는지 확인 - Sandbox 환경의 API 제약을 고려하여 브라우저 내장 다이얼로그나 클립보드 API 대신 호스트 통신 기반의 대체 UI 설계 검토

태그

#MCP #API Serialization #CSS Specificity #FastMCP #Sandbox

원문 읽기