TL;DR

  • WebMCP는 웹페이지의 기능을 도구로 노출해 AI 에이전트가 화면을 추측하며 조작하는 대신 이름과 설명, 형식이 지정된 입력값을 사용해 기능을 호출하게 하는 방식임.
  • 기존 폼에는 toolname, tooldescription, toolautosubmit 속성을 추가하고 입력 요소마다 선택적으로 toolparamdescription을 지정하면 됨.
  • 폼이 아닌 계산기와 생성기 등은 JavaScript의 document.modelContext.registerTool()로 등록하며, 기존 코드 경로를 호출하고 도구 제거에는 AbortController를 사용함.
  • WebMCP는 Chrome 실험 기능으로, 실제 방문자에게 제공하려면 오리진 트라이얼 토큰이 필요하며 현재 트라이얼은 Chrome 149~162, 2027년 3월 30일 종료 예정임.
  • 사이트 검색, 필터·정렬, 계산기·생성기, 예약·문의 폼이 주요 적용 사례이며, API 변경 가능성에 대비해 기능 감지가 필요함.

해결 방법

  • 마우스에 오븐 장갑을 낀 사람처럼 동작하는 AI 에이전트는 화면을 읽고 검색 입력란과 제출 버튼을 추측한 뒤, 동작이 성공했는지 다시 화면을 읽음. 추측할 때마다 오류가 발생할 가능성이 있음.
  • 페이지가 에이전트에 UI만 제공하면 에이전트는 UI를 스크래핑함. WebMCP는 페이지가 기능을 이름, 설명, 형식이 지정된 입력값을 갖춘 도구로 노출하게 하며, 에이전트는 추측 대신 함수를 호출함.
  • 기존 기능이 폼이라면 폼에 속성 세 개를 추가하고, 각 입력란에는 선택적으로 설명을 지정하면 됨.
  • 예시 폼은 /newsletter/를 대상으로 하는 검색 폼이며, toolname="search_issues"로 도구 이름을 지정함.
  • tooldescription에는 웹 개발, CSS, HTML, JavaScript 관련 뉴스레터 이슈를 검색하고 결과 페이지를 연다는 설명을 지정함.
  • 검색 입력란의 이름은 q이며, toolparamdescription은 검색 키워드를 뜻함. aria-label은 Search issues임.
  • toolautosubmit을 지정해 에이전트가 사용자 클릭 없이 폼을 제출하게 함.
  • 브라우저는 폼을 도구로, 이름이 지정된 각 입력란을 매개변수로 변환함. WebMCP를 모르는 브라우저는 알 수 없는 속성을 무시하므로 다른 방문자의 동작은 달라지지 않음.
  • 이 뉴스레터 페이지의 검색 결과는 ?q=가 붙은 같은 URL에서 표시되며, 페이지의 표준 링크는 계속 /newsletter/를 가리킴. 따라서 검색 엔진은 모든 결과 페이지를 원래 페이지로 통합함.

속성의 의미

  • toolname: 에이전트가 호출하는 도구 이름이며, 동사와 스네이크 케이스를 사용하고 페이지 안에서 고유하게 지정함.
  • tooldescription: 도구의 기능과 실행 후 발생하는 일을 설명함. 모델이 모든 단어를 읽으므로 짧게 작성하고, 모델이 알아야 할 제약을 포함함.
  • toolparamdescription: 각 입력란에 지정하며, 해당 값이 무엇을 뜻하는지 설명함.
  • toolautosubmit: 에이전트가 사용자 클릭 없이 제출하게 하는 속성임. 검색과 필터에 사용하고, 전송·구매·삭제처럼 사용자의 확인이 필요한 작업에는 지정하지 않음.

폼이 아닌 기능

  • 계산기, 생성기, 설정 도구처럼 폼이 아닌 기능은 JavaScript에서 도구로 등록함. 예시는 테두리 반경 생성기에 사용되는 코드의 단순화 버전임.
  • document.modelContext가 있을 때 AbortController를 만들고 registerTool()을 호출함. 도구 이름은 generate_border_radius이며, 입력값은 topLeft와 topRight 숫자임. 두 값의 최솟값은 0, 최댓값은 150이고 topLeft는 필수임.
  • topRight가 생략되면 topLeft와 같은 값으로 처리함. 실행 함수는 기존 setCorners()를 호출해 모서리 미리보기를 바꾸고, border-radius CSS 문자열을 반환함. 슬라이더와 에이전트가 같은 코드를 사용하므로 에이전트가 도구를 호출하면 사용자도 미리보기가 바뀌는 모습을 확인함.
  • 도구를 제거할 때는 controller.abort()를 호출함. 컴포넌트가 마운트 해제되거나 해당 기능이 화면에서 사라질 때 실행함.
  • Chrome은 현재 execute의 반환값을 문자열로 변환함. 에이전트가 읽을 텍스트를 반환하거나, 객체를 직접 JSON.stringify로 변환해 반환함.

실제 방문자에게 활성화하기

  • WebMCP는 아직 Chrome 실험 기능임. 속성을 배포하는 것만으로는 충분하지 않으며, 오리진 트라이얼 토큰이 없으면 document.modelContext는 플래그를 직접 활성화한 방문자에게만 존재함.
  • developer.chrome.com/origintrials에서 도메인을 WebMCP 트라이얼에 등록하고 토큰을 페이지의 <head>에 다음과 같이 추가함: <meta http-equiv="origin-trial" content="YOUR_TOKEN">.
  • 현재 트라이얼은 Chrome 149~162에서 실행되며 2027년 3월 30일 종료 예정임. 로컬호스트에서는 chrome://flags/#enable-webmcp-testing을 활성화함.

콘솔에서 테스트하기

  • 도구가 등록된 페이지의 콘솔에서 document.modelContext.getTools()로 도구 목록을 가져온 뒤, 이름이 generate_border_radius인 도구를 찾아 executeTool()에 { topLeft: 40, topRight: 0 }을 전달함. 반환 결과는 'border-radius: 40px 0px;'임.
  • Failed to parse input arguments 오류가 발생하면 Chrome 버전에서 입력값을 문자열로 요구하는 경우임. Chrome 152에서는 JSON.stringify({ topLeft: 40, topRight: 0 })를 전달해야 함.

적용 사례

  • 사이트 검색: 가장 쉽게 적용할 수 있으며, 대개 이미 폼으로 구현되어 있음.
  • 필터와 정렬: “100달러 미만의 빨간 신발을 보여줘”라는 요청을 여섯 번의 클릭 대신 한 번의 호출로 처리함.
  • 계산기와 생성기: 가격 추정기, 배송비 계산기, CSS 도구 등이 해당함.
  • 예약 및 문의 폼: toolautosubmit을 지정하지 않아 사람이 최종 동작을 제어하게 함.

중요한 이유

  • 폼에 속성 세 개를 추가하는 정도의 작업이며, 기능이 필요하지 않은 방문자에게는 보이지 않음.
  • 도구에는 정해진 계약이 있지만 화면 레이아웃에는 없으므로, 에이전트가 사이트 디자인 변경으로 인해 동작을 잃는 문제를 줄임.
  • 아직 초기 단계이므로 기능 감지를 사용해야 함. API는 바뀔 수 있으며, 페이지가 document.modelContext의 존재에 의존하게 해서는 안 됨.
  • markodenic.com/tools의 여러 생성기가 테두리 반경 생성기처럼 WebMCP 도구를 노출함. 일곱 가지 도구를 추가하면서 진행한 Lighthouse 검사와 겪은 문제는 I Added WebMCP to My Site. Here’s What It Took.에 정리되어 있음.
  • 개발자를 위한 팟캐스트 The Next Commit은 차세대 소프트웨어를 형성하는 도구, 워크플로, 아이디어를 다루는 프로그램임.
  • 사이트에서 검색 폼을 골라 속성 세 개를 추가하는 작업은 5분이 걸림.