🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

웹엠시피가 제공하는 개발자 정의 도구를 파이어크롤의 클라우드 브라우저에서 실행하면, 클로드 코드 같은 헤드리스 에이전트도 DOM 탐색이나 화면 캡처 없이 웹 작업을 단일 도구 호출로 처리할 수 있다.

📌 핵심 요약

• 웹엠시피는 웹사이트가 에이전트에게 도구 이름, 설명, 입력 스키마, 실행 로직을 직접 제공하도록 해 HTML 구조를 추론하는 작업과 토큰 사용을 줄이는 제안이다.
• 현재 웹엠시피 도구는 실제 브라우저 탭 안에서만 호출할 수 있어, 자체 브라우저가 없는 클로드 코드나 사용자 정의 헤드리스 워크플로에서는 곧바로 사용할 수 없다.
• 예제는 예약 양식과 동일한 JSON 스키마를 가진 도구를 등록하고, 호출 시 입력값 설정, 기존 양식 검증, 오류 반환, 확인 창 표시까지 사이트 내부 로직으로 수행한다.
• 파이어크롤에서는 캐시를 사용하지 않는 스크레이프 요청으로 실제 브라우저 세션과 scrapeId를 만든 뒤, 같은 세션에 interact를 호출해 도구를 조회하고 실행한다.
• 이를 작은 실행기로 감싸면 클로드 코드는 로컬 브라우저 설치, 개별 입력 요소 탐색, 화면 캡처 없이 클라우드 브라우저에서 예약 도구를 한 번 호출할 수 있다.

🧩 주요 포인트

1. 사이트가 행동 인터페이스를 명시적으로 제공한다 → 에이전트가 사람용 화면 구조를 역으로 해석하지 않고 필요한 작업을 직접 호출할 수 있다.
2. 웹엠시피의 실제 브라우저 의존성을 파이어크롤 세션이 보완한다 → 브라우저를 설치할 수 없는 온라인 환경이나 CI에서도 동일한 페이지 도구를 사용할 수 있다.
3. 입력 스키마와 기존 검증 로직을 함께 재사용한다 → 필수값과 오류를 구조적으로 다루면서 반복적인 DOM 조작과 확인 절차를 줄일 수 있다.

🧠 상세 정리

1. 웹엠시피가 해결하려는 문제

웹사이트는 이미지, 애니메이션, 접근성 마크업 등 사람의 이용을 전제로 구성되므로, 특정 행동만 수행하려는 에이전트에는 불필요한 정보가 많다. 기존 에이전트가 식당을 예약하려면 페이지의 HTML을 읽고 입력 요소를 하나씩 찾아 값을 채운 다음 제출 버튼을 눌러야 한다. 웹엠시피는 이 과정을 대신해 사이트 개발자가 자바스크립트나 HTML로 에이전트가 수행할 수 있는 행동을 도구로 등록하게 한다. 각 도구에는 이름, 설명, 입력 스키마, 호출 시 실행할 로직이 포함되며 일반적인 엠시피 도구와 유사한 형태를 갖는다. 따라서 예약처럼 여러 화면 조작이 필요한 작업도 하나의 명시적인 도구 호출로 바뀌어, DOM 추론과 반복 조작에 드는 작업 및 토큰을 줄일 수 있다.

2. 헤드리스 에이전트의 제약과 파이어크롤의 역할

원문이 지적하는 핵심 제약은 현재 웹엠시피가 실제로 열린 브라우저 탭 안에서만 동작한다는 점이다. 크롬 웹엠시피 문서 기준으로 헤드리스 브라우저의 에이전트가 이러한 도구를 직접 호출하는 방식은 지원되지 않으며, 브라우저 자체에 도구를 사용할 에이전트가 연결되어야 한다. 클로드 코드나 사용자 정의 에이전트 워크플로처럼 기본적으로 브라우저 탭을 갖지 않는 실행 환경에는 이 조건이 장애물이 된다. 파이어크롤의 interact 엔드포인트는 에이전트가 제어할 수 있는 실제 브라우저를 클라우드 샌드박스에서 실행해 이 간극을 메운다. 에이전트는 로컬 브라우저를 배포하지 않고도 프롬프트나 코드를 통해 해당 탭을 조작하고, 페이지 안에 등록된 웹엠시피 도구를 이용할 수 있다.

3. 예약 데모와 웹엠시피의 현재 제공 상태

예제 사이트는 가상의 식당인 르 프티 비스트로이며, 사용자가 양식을 채워 좌석을 예약하는 구조다. 이 사이트는 웹엠시피 도구가 포함된 구글의 프렌치 비스트로 데모를 바탕으로 하지만, 작성자는 비교 기준을 만들기 위해 처음에는 도구를 모두 제거했다. 도구가 없는 상태는 크롬에서 웹엠시피 시험 기능을 활성화하고 웹엠시피 도구 검사기 확장 기능을 설치해 확인할 수 있으며, 저장소의 stage-1 브랜치에는 도구를 다시 추가한 버전이 제시된다. 글 작성 시점의 설명에 따르면 웹엠시피는 크롬 157에 기본 탑재되고 2026년 11월경 안정판으로 출시되는 일정이 제시됐지만, 당시 안정판은 150이어서 아직 플래그와 오리진 트라이얼 뒤에 있었다. 이에 따라 데모에서는 @mcp-b/webmcp-polyfill 패키지를 초기화해 기본 탑재 전의 환경에서도 도구 등록 기능을 사용한다.

4. 예약 도구의 등록과 실행 로직

폴리필을 초기화한 뒤 document.modelContext.registerTool로 book_table_le_petit_bistro라는 예약 도구를 등록한다. 입력 스키마는 일반 JSON 스키마로 작성되며 이름, 전화번호, 날짜, 시간, 인원, 좌석 선호, 특별 요청을 정의하고 그중 이름, 전화번호, 날짜, 시간, 인원을 필수값으로 지정한다. 이 구조 덕분에 에이전트는 페이지의 입력 요소를 조사하지 않고도 어떤 값이 필요하고 어떤 값이 선택 사항인지 알 수 있다. 실행 함수는 전달받은 값을 실제 양식 필드에 넣고 사이트의 기존 validateForm() 검사를 호출하며, 검증 오류가 있으면 오류 목록과 isError: true를 반환한다. 검증을 통과하면 확인 창을 표시하고 예약 내용을 도구 결과로 돌려주므로, 사이트가 이미 보유한 입력 처리와 검증 로직을 그대로 에이전트 호출에 재사용한다.

5. 로컬 기준선인 에이전트 브라우저 방식

작성자는 파이어크롤을 도입하기 전에 agent-browser 명령줄 도구로 같은 원리를 로컬에서 확인한다. 스크립트는 먼저 주소를 실제 브라우저에 열어 탭을 유지한 뒤, eval 명령으로 페이지 안의 document.modelContext.getTools()를 실행해 등록된 도구의 이름, 설명, 입력 스키마를 읽는다. 도구 호출도 두 번째 eval에서 이름에 맞는 항목을 찾고 document.modelContext.executeTool()에 전달하는 방식으로 처리할 수 있어, HTML 스크레이핑이나 화면 캡처가 필요하지 않다. 다만 이 접근은 실행 머신에 실제 크롬이 있어야 하며, 최초 실행 시 테스트용 크롬을 내려받는 설치 과정도 요구한다. 브라우저를 설치하거나 실행할 수 없는 온라인 환경, CI 파이프라인, 통제가 엄격한 업무용 장비에서는 이러한 로컬 방식 자체를 사용할 수 없다는 한계가 있다.

6. 파이어크롤 브라우저 세션 생성과 도구 탐색

파이어크롤 방식은 노드용 SDK를 설치한 다음 페이지를 스크레이프하고, 생성된 세션에 상호작용 요청을 보내는 순서로 진행된다. 첫 스크레이프 요청에는 maxAge: 0을 지정해 캐시 결과가 아니라 실제 브라우저 로드를 강제하며, 응답 메타데이터에서 이후 요청에 사용할 scrapeId를 얻는다. 원문은 캐시에서 제공된 스크레이프 결과의 식별자 뒤에는 살아 있는 브라우저 세션이 없을 수 있으므로 이 설정이 필요하다고 설명한다. 이어서 같은 scrapeId로 interact를 호출하고, 이미 세션에 연결된 플레이wright의 page 객체에서 page.evaluate()를 실행해 document.modelContext.getTools()의 결과를 읽는다. 작업이 끝난 뒤에는 stopInteraction을 호출해 해당 브라우저 세션을 명시적으로 종료한다.

7. 도구 호출과 인수 전달 방식

실제 예약을 수행할 때는 도구를 탐색했던 것과 동일한 scrapeId를 사용해 두 번째 interact 요청을 보낸다. 브라우저 페이지 안에서 등록 도구 목록을 가져온 후 지정한 이름과 일치하는 도구를 찾고, 존재하지 않으면 도구를 찾을 수 없다는 결과를 반환한다. 호출 인수는 파이어크롤 전송 과정에서 문자열 따옴표가 깨지는 문제를 피하도록 베이스64로 인코딩하고, 페이지 내부에서 atob와 JSON 파싱을 통해 원래 객체로 복원한다. 복원한 인수는 JSON 문자열로 바꿔 document.modelContext.executeTool()에 전달되며, 실행 결과도 직렬화되어 에이전트에 돌아온다. 파이어크롤은 노드나 파이썬의 플레이wright 코드와 배시 모드의 에이전트 브라우저 명령을 지원하지만, 이 예제에서는 기본 코드 모드인 노드 플레이wright를 직접 사용하는 방식을 더 간결한 선택으로 제시한다.

8. 클로드 코드에서의 사용 흐름과 확인된 경계

도구 탐색과 호출 절차를 작은 실행기로 감싸면 클로드 코드는 주소가 제공하는 웹엠시피 도구와 각 도구의 필수·선택 입력값을 정확히 확인할 수 있다. 실행 중에는 파이어크롤 대시보드에 일시적으로 생성된 클라우드 브라우저 세션이 표시되며, 에이전트는 자연어 예약 요청을 해당 도구 호출로 변환한다. 원문은 사용자가 시간이나 전화번호 같은 필수값을 생략하면 에이전트가 이를 추가로 묻거나 값을 만들어 넣는 흐름을 설명하며, 최종 예약은 한 번의 도구 호출로 처리된다고 말한다. 이 방식에서는 로컬 브라우저 설치, 개별 입력 요소 스크레이핑, 작업 확인용 화면 캡처가 필요하지 않고 예제 실행은 클라우드에서 1분 이내에 끝난 것으로 소개된다. 다만 제공된 원문은 마지막의 주의사항 절 제목 직후에 끊겨 있으므로, 그 뒤에 있었을 추가 제약이나 권장 사용 조건은 확인 가능한 내용에 포함되지 않는다.

🧾 핵심 주장 / 시사점

• 웹엠시피는 사람용 화면을 없애는 방식이 아니라, 같은 페이지에 에이전트용 행동 인터페이스를 병행해 제공하는 구조이므로 기존 양식과 검증 로직을 유지하면서 자동화 경로를 단순화한다.
• 파이어크롤의 핵심 가치는 웹엠시피 자체를 별도로 구현하는 데 있지 않고, 브라우저 안에서만 보이는 document.modelContext를 헤드리스 실행 환경이 접근할 수 있도록 실제 클라우드 브라우저 세션을 제공하는 데 있다.
• 토큰과 조작 단계를 줄이는 효과는 사이트가 적절한 이름, 설명, JSON 스키마, 실행 로직을 가진 도구를 등록하고 에이전트가 살아 있는 동일 세션을 유지할 때 성립한다.

✅ 액션 아이템

• 헤드리스 에이전트 웹 작업 중 웹엠시피 도구로 옮길 대상과 기존 양식 JSON 스키마 정합 범위를 정의한다.
• 파이어크롤 비캐시 스크레이프로 브라우저 세션·scrapeId를 만든 뒤 동일 세션 interact 도구 조회·실행 경로를 점검한다.
• 로컬 브라우저·DOM 탐색·화면 캡처 없이 예약 도구 단일 호출로 대체 가능한 단계를 비교·우선순위를 정한다.

❓ 열린 질문

• 실제 브라우저 탭에만 묶인 웹엠시피 호출 제약을 파이어크롤 세션 외에 어떤 방식으로 완화할 수 있는가?
• 입력 스키마와 사이트 검증·오류 반환을 재사용할 때 에이전트가 다룰 응답 형식의 기준은 무엇인가?
• CI·온라인 환경에서 scrapeId 세션 유지와 도구 호출 성공을 어떤 기준으로 판단할 것인가?