Next.js 앱에 WebMCP를 추가하는 방법
AI 에이전트는 웹 앱을 이해하는 데 종종 어려움을 겪습니다. DOM을 스크래핑하여 버튼의 기능을 추측하곤 하는데, 이는 오류와 환각(hallucination) 현상으로 이어집니다.
WebMCP는 이 문제를 해결합니다. WebMCP는 브라우저에 modelContext API를 추가하는 W3C 표준입니다. 추측하는 대신, Next.js 앱이 에이전트에게 실행 가능한 함수가 무엇인지 정확하게 알려줍니다.
WebMCP vs Anthropic MCP
Anthropic MCP는 서버에서 실행됩니다. JSON-RPC를 사용하여 데이터베이스나 API에 연결하며, 브라우저 외부에서 동작합니다.
WebMCP는 브라우저 탭 내에서 실행됩니다. 도구를 로컬에 등록하며, 사용자의 기존 세션을 활용합니다. 별도의 인증이나 백엔드가 필요하지 않습니다.
두 기술은 함께 작동할 수 있습니다. 백엔드 작업에는 MCP를, 프론트엔드 상호작용에는 WebMCP를 사용할 수 있습니다.
도구를 노출하는 두 가지 방법:
HTML Forms: 폼에
toolname및tooldescription속성을 추가합니다. 에이전트는 JavaScript 없이도 도구와 파라미터를 확인할 수 있습니다. 검색 및 필터 기능에 사용하세요.JavaScript: 동적 로직을 위해
navigator.modelContextAPI를 사용합니다. 이는 여러 단계로 이루어진 흐름(multi-step flows)에 가장 적합합니다.
Next.js에서의 구현
브라우저 지원을 위한 폴리필(polyfill)을 설치합니다:
npm install @mcp-b/global @mcp-b/react-webmcp레이아웃에서 폴리필을 초기화하기 위해
WebMCPProvider를 생성합니다.클라이언트 컴포넌트에서
useWebMCP훅을 사용합니다. 이 훅은 도구 등록 및 정리를 자동으로 처리합니다.
예시 도구 설정:
useWebMCP({
name: 'searchProducts',
description: 'Search the product catalog.',
inputSchema: z.object({
query: z.string(),
category: z.string().optional(),
}),
execute: async ({ query, category }) => {
const res = await fetch(`/api/products?q=${query}`);
return res.json();
},
});
권장 사항
- HTTPS를 사용하세요. 프로덕션 환경에서 WebMCP는 보안 연결이 필요합니다.
- 도구 개수를 적게 유지하세요. 도구가 너무 많으면 AI 컨텍스트가 비대해지고 추론 속도가 느려집니다. 페이지당 도구 수를 50개 미만으로 유지하세요.
- 상세한 설명을 제공하세요. 에이전트는 도구를 언제 사용해야 할지 이해하기 위해 이 문자열에 의존합니다.
- 서비스 레이어를 사용하세요. 도구 핸들러 내부에서 React 상태(state)에 의존하지 마세요. 오래된 데이터(stale data)를 방지하려면 일반 함수를 사용하세요.
테스트 방법
Chrome 146 이상 버전을 사용하세요. chrome://flags에서 WebMCP 플래그를 활성화합니다. AI 에이전트 없이 도구를 테스트하려면 Model Context Tool Inspector 확장을 사용하세요.
WebMCP는 에이전트 기반 웹 브라우징의 미래입니다. 브라우저에서 기본적으로 지원하게 될 때를 대비해 지금 바로 구현을 시작하세요.
Source: https://dev.to/webtoolshub/how-to-add-webmcp-to-your-nextjs-app-complete-2026-guide-pbp