WebMCP en Next.js y React: registre herramientas para agentes de IA correctamente

Si su producto funciona con Next.js o React, WebMCP encaja muy bien: una herramienta es una función pequeña, y sus rutas de API ya hacen el trabajo real. Esta guía muestra un patrón limpio. ¿Es nuevo en el tema? Empiece por qué es WebMCP.

Registre las herramientas en un componente de cliente

document.modelContext solo existe en el navegador, así que el registro debe ir en useEffect. No renderice nada y pase un AbortSignal para que las herramientas desaparezcan cuando el visitante salga de la página:

'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;
}

Añada <SearchTool /> al layout o a la página donde la herramienta tenga sentido. El Strict Mode de React ejecuta los efectos dos veces en desarrollo, y la limpieza anterior se ocupa de ello.

Mantenga la lógica en una ruta de API

La herramienta es solo una capa fina. La validación, los límites y los permisos van en el servidor, donde un visitante no puede cambiarlos:

// 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 })));
}

Formularios como herramientas

En un formulario sencillo, añada toolname y tooldescription al elemento <form>. React pasa a la página estos atributos desconocidos en minúsculas. El navegador rellena el formulario y, por defecto, el visitante sigue pulsando el botón.

Reglas de seguridad

• Empiece con solo lectura. Primero búsqueda y detalles; márquelos con readOnlyHint.
• Pregunte antes de actuar. Marque las acciones de carrito, reserva y formularios con consequentialHint para que el visitante confirme.
• Compruebe en el servidor. El navegador no es una barrera de seguridad, así que valide cada entrada y cada permiso en su backend.
• Devuelva lo mínimo. Envíe solo lo que un cliente puede ver, nunca datos de administración ni registros de otros clientes.

Pruébelo

1. Use una versión reciente de Chrome con WebMCP activado, mediante la prueba de origen o la opción de pruebas.
2. Llame a cada herramienta con entradas correctas e incorrectas.
3. Compruebe que los visitantes normales no notan ningún cambio.
4. Ejecute el comprobador WebMCP gratuito en la página exacta donde están sus herramientas.

¿Prefiere que lo hagamos por usted?

Añadimos WebMCP a productos con Next.js y React, desde una auditoría de preparación gratuita hasta herramientas probadas. Conozca nuestros servicios de integración de WebMCP y de desarrollo con Next.js.