WebMCP 실전 예제 — 기존 웹앱의 상태 저장소에 AI 도구를 연결하는 방법과 등록 코드 살펴보기

핵심 메시지

• WebMCP 는 이미 상태 저장소와 렌더링이 분리된 웹앱이라면 적은 작업만으로 AI 제어를 붙일 수 있게 해주는 표준이다.
• 발표자는 3D 프린팅 정리 시스템 'Multiboard' 의 파라메트릭 모델 편집기를 WebMCP 호환으로 다시 만들어, 브라우저에서 자연어로 치수를 바꾸는 데모를 보여준다.
• 도구 등록은 이름·설명·입력 스키마·실행 함수 네 가지로 끝나며, 설명문이 AI 가 어떤 도구를 쓸지 판단하는 근거가 된다.
• 잘못된 입력이 들어오면 그냥 실패시키지 말고 무엇이 틀렸는지 알려주는 응답 텍스트를 돌려줘야 AI 가 스스로 교정한다.
• 사이트가 AI 를 직접 호스팅할 필요 없이 훅 몇 개만 열어주면 되므로, 도입 비용 대비 사용자 가치 상승 폭이 크다.

쉽게 이해하기

잭 헤링턴은 최근 WebMCP 를 계속 만져보며 이 표준을 적극적으로 권한다고 말한다. 그가 강조하는 핵심은 진입 장벽이 낮다는 점이다. 데이터가 저장소에 있고 그것을 무언가가 렌더링하는 전형적인 구조, 예컨대 리덕스와 리액트 조합이나 Zustand 와 리액트 조합을 이미 쓰고 있다면, 그 저장소를 WebMCP 에 연결하는 것만으로 준비가 끝난다는 것이다.

예시는 그의 차고에서 출발한다. 작업 공간을 정리하려고 'Multiboard' 라는 3D 프린팅 시스템을 쓰는데, 기성품으로 구할 수 없는 부품은 웹상의 파라메트릭 빌더로 직접 만든다. 이 빌더는 OpenSCAD 코드를 생성하고, 내부 치수 같은 옵션 값을 입력하면 3D 모델이 나온다. 문제는 캘리퍼스로 잰 수치를 일일이 입력 칸에 옮겨 적어야 하는 인터페이스가 불편하고, WebMCP 가 없어 AI 와 대화하며 파라미터를 맡길 수 없다는 점이었다.

그래서 하룻저녁 만에 클로드를 시켜 같은 기능을 다시 만들었다. OpenSCAD 코드는 그대로 두고 WASM 으로 실행해 메시를 얻은 뒤 three.js 로 렌더링하는 구조다. 여기에 MCP-B 브라우저 확장을 설치하니 localhost:3000 에서 제공하는 도구들이 잡혔다. 파라미터 목록 조회, 값 읽기, 값 설정 세 가지가 실제로 모델을 움직이는 도구다. "높이를 81밀리미터로 맞추고 앞면 컷아웃을 없애 달라"고 말하면 도구가 순서대로 호출되고, 모델과 뷰가 분리된 구조 덕분에 화면이 자동으로 다시 그려진다.

구현은 src/mcp 아래 등록 코드에 모여 있다. 앱이 시작될 때 registerWebMcpTools 함수를 호출하고, WebMCP 컨텍스트가 없으면 폴리필을 채운 뒤 Navigator 에서 모델 컨텍스트를 가져와 도구를 등록한다. 등록 항목은 도구 이름, 설명, 입력 스키마, 실행 함수다. 발표자는 설명문이 "이 도구가 지금 상황에 맞는가"를 AI 가 판단하는 근거이고, 입력 스키마는 인자를 어떻게 넘길지 정하는 부분이라고 짚는다.

값을 바꾸는 setParameter 도구의 코드는 대부분 입력 검증이다. AI 가 보낸 값이 유효하지 않으면 무엇이 잘못됐고 어떻게 고치면 되는지 알려주는 응답 텍스트를 돌려준다. 값이 통과하면 projectActions.setOverride 를 거쳐 TanStack Store 로 만든 projectStore 의 상태를 갱신하고, 오버라이드 값과 변경 이력을 함께 쌓는다. 상태가 바뀌면 UI 가 다시 그려지고 OpenSCAD 코드가 WASM 으로 재실행돼 새 메시가 나온다.

주요 인사이트

• AI 연동의 난이도는 모델을 붙이는 데 있는 게 아니라 앱의 상태 관리가 정리돼 있는지에 달려 있다. 저장소 하나로 상태가 모이고 변경 시 자동 재렌더링되는 구조라면 도구를 붙였을 때 화면 갱신까지 공짜로 따라온다.
• 도구 설명문은 문서가 아니라 라우팅 규칙이다. AI 는 설명을 읽고 도구를 고르기 때문에, 설명이 모호하면 기능이 멀쩡해도 호출되지 않는다.
• 검증 실패 처리를 '에러 반환' 이 아니라 '교정 안내' 로 설계한 점이 인상적이다. 사람 사용자와 달리 AI 는 되돌아온 텍스트를 읽고 재시도하므로, 오류 메시지의 품질이 곧 성공률이 된다.
• WebMCP 는 사이트 소유자가 모델 비용이나 인프라를 떠안지 않아도 되는 구조다. 사용자가 이미 쓰는 AI 클라이언트가 브라우저를 통해 사이트의 도구를 호출하기 때문이다.
• 기존 기능이 그 자체로 가치 있는 시스템일수록 효과가 크다. 발표자의 사례처럼 치수를 넣어 모델을 뽑고 STL 로 출력하는 흐름이 이미 완성돼 있으면, 훅 몇 개를 여는 것만으로 사용성이 크게 달라진다.

자주 묻는 질문

관련 AI 소식