WebMCP in Next.js and React: Register AI-Agent Tools the Right Way

If your product runs on Next.js or React, WebMCP fits neatly: a tool is a small function, and your API routes already do the real work. This guide shows a clean pattern. New to the topic? Start with what WebMCP is.

Register tools in a client component

document.modelContext exists only in the browser, so registration belongs in useEffect. Render nothing, and pass an AbortSignal so that tools disappear when the visitor leaves the page:

'use client';
import { useEffect } from 'react';

export default function SearchTool() {
  useEffect(() => {
    const mc = document.modelContext || navigator.modelContext;
    if (!mc?.registerTool) return undefined; // browsers without WebMCP skip this
    const controller = new AbortController();
    mc.registerTool({
      name: 'search_products',
      description: 'Search the catalog. Returns up to 5 products with price and link.',
      inputSchema: {
        type: 'object',
        properties: { query: { type: 'string' } },
        required: ['query'],
      },
      annotations: { readOnlyHint: true },
      execute: async ({ query }, { signal }) => {
        const res = await fetch('/api/search?q=' + encodeURIComponent(query), { signal });
        return JSON.stringify(await res.json());
      },
    }, { signal: controller.signal });
    return () => controller.abort();
  }, []);
  return null;
}

Add <SearchTool /> to the layout or page where the tool makes sense. React Strict Mode runs effects twice in development, and the clean-up above handles that.

Keep the logic in an API route

The tool is only a thin wrapper. Validation, limits and permissions belong on the server, where a visitor cannot change them:

// app/api/search/route.js
import { NextResponse } from 'next/server';

export async function GET(request) {
  const q = (request.nextUrl.searchParams.get('q') || '').slice(0, 80);
  if (!q) return NextResponse.json({ error: 'missing_query' }, { status: 400 });
  const items = await searchCatalog(q, { limit: 5 }); // your own function
  return NextResponse.json(items.map(({ name, price, url }) => ({ name, price, url })));
}

Forms as tools

For a simple form, add toolname and tooldescription to the <form> element. React passes these unknown lowercase attributes through to the page. The browser fills in the form and, by default, the visitor still presses the button.

Safety rules

• Start read-only. Search and details first; mark them with readOnlyHint.
• Ask before acting. Mark cart, booking and form actions with consequentialHint, so the visitor confirms.
• Check on the server. The browser is not a security boundary, so validate every input and permission in your backend.
• Return little. Send only what a customer may see, never admin data or other customers’ records.

Test it

1. Use a recent Chrome with WebMCP turned on, through the origin trial or the testing flag.
2. Call each tool with good and bad inputs.
3. Check that normal visitors see no change.
4. Run the free WebMCP checker on the exact page where your tools live.

Want it done for you?

We add WebMCP to Next.js and React products, from a free readiness audit to tested tools. See our WebMCP integration services and Next.js development.