How to Add WebMCP to Your Next.js App
AI agents often struggle to understand web apps. They scrape the DOM and guess what buttons do. This leads to errors and hallucinations.
WebMCP solves this. It is a W3C standard that adds a modelContext API to browsers. Instead of guessing, your Next.js app tells the agent exactly what functions it can run.
WebMCP vs Anthropic MCP
Anthropic MCP runs on the server. It uses JSON-RPC to connect to databases or APIs. It lives outside the browser.
WebMCP runs in the browser tab. It registers tools locally. It uses the user's existing session. No extra auth or backend is needed.
They work together. You can use MCP for backend tasks and WebMCP for frontend interactions.
Two ways to expose tools:
HTML Forms: Add toolname and tooldescription attributes to your forms. The agent sees the tool and the parameters without any JavaScript. Use this for search and filters.
JavaScript: Use the navigator.modelContext API for dynamic logic. This is best for multi-step flows.
Implementation in Next.js
Install the polyfill for browser support: npm install @mcp-b/global @mcp-b/react-webmcp
Create a WebMCPProvider to initialize the polyfill in your layout.
Use the useWebMCP hook in your client components. This hook handles tool registration and cleanup automatically.
Example tool setup:
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();
},
});
Best Practices
- Use HTTPS. WebMCP requires a secure connection in production.
- Keep tool counts low. Too many tools bloat the AI context and slow down reasoning. Stay under 50 tools per page.
- Provide rich descriptions. Agents rely on these strings to understand when to use a tool.
- Use a service layer. Do not rely on React state inside tool handlers. Use plain functions to avoid stale data.
Testing
Open Chrome 146 or newer. Enable the WebMCP flag in chrome://flags. Use the Model Context Tool Inspector extension to test your tools without an AI agent.
WebMCP is the future of agentic web browsing. Start implementing it now so you are ready when browsers enable it by default.
Source: https://dev.to/webtoolshub/how-to-add-webmcp-to-your-nextjs-app-complete-2026-guide-pbp