WebMCP는 웹사이트를 에이전트가 즉시 사용할 수 있는 상태(agent-ready)로 만듭니다. 에이전트에게 UI를 클릭하는 방법을 가르치는 대신, 애플리케이션이 무엇을 할 수 있는지 가르치십시오.

1. WebMCP란 무엇인가?

WebMCP (Web Model Context Protocol)는 W3C Web Machine Learning Working Group에서 제안하고 Google Chrome이 주도하여 개발 중인 웹 표준입니다. 이는 웹 애플리케이션이 브라우저 내에서 실행되는 AI 에이전트에게 구조화된 도구(tools)를 노출할 수 있게 해줍니다.

역사적으로 AI 에이전트가 웹사이트와 상호작용하고자 할 때, 다음과 같은 과정을 거쳐야 했습니다:

• 버튼을 찾기 위해 DOM 분석
• 양식(form) 필드 감지 및 채우기
• 페이지 탐색(navigation) 시뮬레이션
• 스크린샷 해석

**작동(actuation)**이라고 불리는 이 방식은 취약합니다. UI가 변경되면 에이전트가 고장 납니다. 버튼의 위치가 바뀌거나 CSS 클래스가 업데이트되면 에이전트의 전체 동작이 무너집니다.

WebMCP는 이 패러다임을 뒤집습니다: 에이전트에게 UI를 사용하는 방법을 가르치는 대신, 애플리케이션이 무엇을 할 수 있는지 알려주는 것입니다.

핵심 개념 (Core Concepts)

WebMCP는 세 가지 핵심 문제를 해결합니다:

1. 발견 (Discovery): 페이지가 에이전트에게 도구(checkout, filter_results 등)를 등록하는 표준화된 방식.
2. JSON 스키마 (JSON Schemas): 입력과 출력에 대한 명시적인 정의를 통해 환각(hallucination)과 오해를 줄임.
3. 상태 (State): 현재 페이지 컨텍스트에 대한 공유된 이해를 제공하여, 에이전트가 어떤 리소스를 사용할 수 있는지 알 수 있게 함.

2. 왜 WebMCP인가?

작동(Actuation) 방식의 문제점

에이전트가 UI 상호작용(actuation)에 의존할 때, 다음과 같은 문제에 직면하게 됩니다:

• 취약성 (Fragility): UI의 모든 변경 사항(CSS 클래스, DOM 구조, 버튼 위치 등)이 에이전트를 고장 냅니다.
• 다단계 모호성 (Multi-step ambiguity): 모든 단계가 해석의 여지가 있습니다. 드롭다운 메뉴를 잘못 이해하면 전체 워크플로우가 탈선합니다.
• 느린 속도 (Slowness): DOM 분석, 요소 탐색, 클릭 시뮬레이션 등 모든 과정에 시간이 소요됩니다.
• 접근성 격차 (Accessibility gaps): 에이전트는 aria-label이나 시맨틱 HTML (semantic HTML)이 없는 요소를 이해할 수 없습니다.

WebMCP가 가져오는 변화

작동(Actuation):  에이전트 → "이 버튼은 무엇을 하나요?" → DOM 분석 → 추측 → 클릭
WebMCP:          에이전트 → "어떤 도구를 사용할 수 있나요?" → getTools() → checkout() 호출

속도 및 신뢰성 (Speed & Reliability): WebMCP는 브라우저의 내부 시스템을 사용하므로 클라이언트와 도구 간의 통신이 거의 즉각적입니다. 원격 서버로의 왕복(round-trip)이 필요하지 않습니다.

UI 독립성 (UI-Independent): WebMCP 도구는 디자인이 아닌 애플리케이션 로직에 연결됩니다. 에이전트의 상호작용 능력을 망가뜨리지 않고도 사이트를 재설계할 수 있습니다.

제어권 확보 (You're in Control): 에이전트가 사이트와 상호작용하는 방식을 직접 정의합니다. 에이전트가 올바른 버튼을 찾기를 기대하는 대신, 무엇을 해야 할지 정확하게 지시할 수 있습니다.

신뢰 및 브랜드 (Trust & Brand): 도구가 페이지 상에서 가시적으로 실행됩니다. 사용자는 작업이 예상대로 완료되는 것을 확인하며, 브랜드 경험을 온전히 유지할 수 있습니다.

점진적 향상 (Progressive Enhancement): WebMCP는 추가적인 레이어입니다. WebMCP를 지원하지 않는 브라우저에서도 애플리케이션은 정상적으로 작동합니다.

3. WebMCP vs MCP

가장 흔한 질문: "WebMCP가 MCP를 대체하게 될까요?"

답변: 아니요. Chrome 팀이 밝힌 바와 같이, WebMCP와 MCP는 서로 다른 문제를 해결합니다. 이들은 함께 작동하도록 설계되었습니다.

비교 표

이들이 함께 작동하는 방식

Chrome 팀의 비유:

MCP는 회사의 24시간 콜센터와 같습니다. 어디서든 접근 가능하며, 언제든 핵심 작업을 처리합니다.

WebMCP는 동일한 회사의 매장 내 전문가와 같습니다. 매장에 있을 때(사이트가 열려 있을 때)만 이용 가능하지만, 문맥에 특화된(context-specific) 빠르고 정확한 서비스를 제공합니다.

가장 효과적인 에이전트형 애플리케이션 (agentic applications)은 이 두 가지를 모두 사용합니다:

1. MCP는 백그라운드 API 작업, 데이터 페칭 (data fetching), 배치 작업 (batch jobs)을 처리합니다. 플랫폼에 구애받지 않으며(platform-agnostic) 항상 사용 가능합니다.
2. WebMCP는 사용자가 사이트를 방문할 때 작동합니다. 라이브 탭 문맥 (live tab context) 내에서 즉각적이고 신뢰할 수 있는 상호작용을 제공합니다.

┌──────────────────────────────────────┐
│           AI Agent (Browser)         │
├──────────────────────────────────────┤
...

4. WebMCP 아키텍처 (Architecture)

WebMCP는 두 가지 API 표면 (API surfaces)을 노출합니다:

명령형 API (Imperative API, JavaScript)

// document.modelContext.registerTool() — 도구 등록 (tool registration)
// document.modelContext.getTools() — 도구 탐색 (tool discovery)
// document.modelContext.executeTool() — 수동 도구 호출 (manual tool invocation)
...

참고: navigator.modelContext는 Chrome 150부터 사용 중단 (deprecated) 되었습니다. 대신 document.modelContext를 사용하세요.

선언형 API (Declarative API, HTML)

<form
  toolname="search_cars"
  tooldescription="Search for cars based on criteria"
...

출처 격리 및 권한 모델 (Origin Isolation & Permission Model)

WebMCP API는 두 계층의 보안 모델로 보호됩니다:

1. 출처 격리 (Origin Isolation): WebMCP는 출처 격리된 (origin-isolated) 문서에서만 작동합니다. Origin-Agent-Cluster: ?0 헤더가 설정되어 있거나 document.domain이 사용되는 경우 비활성화됩니다.

2. 권한 정책 (Permissions Policy): 두 API 모두 tools 권한 정책에 의해 제어됩니다. 기본값은 self로, 최상위(top-level) 및 동일 출처(same-origin) 문맥에서만 도구를 등록할 수 있습니다. 교차 출처 (cross-origin) iframe의 경우 allow="tools"를 추가해야 합니다.

<iframe src="https://example.com/widget" allow="tools"></iframe>

도구 생명주기 (Tool Lifecycle)

Register (등록) ──► Discover (탐색) ──► Execute (실행) ──► Unregister (등록 해제)
   │                         │
   │                         └── AbortSignal을 통해 취소 가능
...

5. 브라우저 + 에이전트 + React 애플리케이션 흐름 (Browser + Agent + React Application Flow)

사용자, AI 에이전트, 그리고 WebMCP가 활성화된 React 애플리케이션 간의 상호작용 흐름:

1. 사용자가 사이트 접속
   React 앱 마운트 (mount)
   > useWebMcp 훅 (hooks) 실행
...

6. Chrome Origin Trial 및 요구 사항 (Chrome Origin Trial & Requirements)

Origin Trial

WebMCP는 현재 Chrome 149+ 버전에서 Origin Trial 단계에 있습니다.

Origin Trial 등록하기

로컬 개발용 Chrome 플래그 (Local Development Chrome Flag)

프로덕션 적용 전 로컬 개발을 위해:

1. chrome://flags/#enable-webmcp-testing으로 이동합니다.
2. 플래그를 Enabled로 설정합니다.
3. Chrome을 재시작합니다.

브라우저 지원 확인 (Browser Support Check)

const isWebMCPSupported = (): boolean => {
  return typeof document !== "undefined" && "modelContext" in document;
};

Model Context Tool Inspector 확장 프로그램

Inspector Extension을 설치하여 다음을 수행할 수 있습니다:

• 모든 페이지에서 등록된 도구 (tools) 확인
• 도구 수동 호출
• JSON Schema 정의 검증
• 자연어 프롬프트에 대한 에이전트 응답 테스트

7. 명령형 API (Imperative API)

명령형 API (Imperative API)를 사용하면 JavaScript로 도구를 정의할 수 있습니다. 폼 입력 (form input), 사이트 탐색 (site navigation), 상태 관리 (state management) 등 모든 함수를 도구로 노출할 수 있습니다.

핵심 API (Core API)

// 도구 등록
await document.modelContext.registerTool({
  name: "get_order_status",
...

도구 제거를 위한 AbortSignal

const controller = new AbortController();

await document.modelContext.registerTool(
...

도구 탐색 및 수동 실행 (Tool Discovery & Manual Execution)

// 동일 출처 (Same-origin) 도구
const tools = await document.modelContext.getTools();

...

교차 출처 도구 공유 (Cross-Origin Tool Sharing)

// https://partner.org 에서
await document.modelContext.registerTool(
  {
...

8. 선언형 API (Declarative API)

8. 선언형 API (Declarative API)

선언형 API (Declarative API)를 사용하면 HTML 폼 (form) 요소에 속성을 추가하는 것만으로 도구 (tools)를 정의할 수 있습니다. JavaScript를 작성하지 않고도 기존의 폼을 에이전트 (agent)가 사용할 수 있는 도구로 전환할 수 있습니다.

HTML 속성 (Attributes)

예시: 고객 지원 요청 폼 (Support Request Form)

<form
  toolname="createSupportRequest"
  tooldescription="고객 지원 요청을 제출합니다."
...

브라우저는 이 폼을 자동으로 JSON 스키마 (JSON Schema)로 변환합니다.

SubmitEvent.agentInvoked 및 CSS 의사 클래스 (Pseudo-Classes)

document.querySelector("form").addEventListener("submit", (e) => {
  e.preventDefault();
  if (e.agentInvoked) {
...

/* 에이전트가 폼을 활성화할 때 */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
...

9. React에서 명령형 API (Imperative API) 사용하기

타입 정의 (Type Definitions)

// types/webmcp.ts

export interface WebMCPToolDefinition<
...

기본 사용법 (Basic Usage)

// components/ProductSearch.tsx
import { useEffect } from "react";

...

10. React Hooks: useWebMcp

기본 훅 (Basic Hook)

// hooks/useWebMcp.ts
import { useEffect, useRef } from "react";
import type { WebMCPToolDefinition, RegisterToolOptions } from "@/types/webmcp";
...

상태 인식 버전 (State-Aware Version)

// hooks/useWebMcp.ts (continued)

interface UseWebMcpStateAwareOptions<
...

사용 예시 (Usage Examples)

// features/cart/Checkout.tsx

export function Checkout() {
...

// features/admin/UserManagement.tsx

export function UserManagement() {
  const { role } = useUserRole();

  useWebMcp({
    name: "createUser",
    description: "이메일, 역할, 부서 정보를 사용하여 새로운 사용자 계정을 생성합니다.",
    inputSchema: {
      type: "object",
      properties: {
        email: