WebMCP dans Next.js et React : enregistrer des outils pour agents IA dans les règles

Si votre produit repose sur Next.js ou React, WebMCP s’intègre très bien : un outil est une petite fonction, et vos routes API font déjà le vrai travail. Ce guide présente une méthode propre. Vous découvrez le sujet ? Commencez par ce qu’est WebMCP.

Enregistrer les outils dans un composant client

document.modelContext n’existe que dans le navigateur : l’enregistrement se fait donc dans useEffect. N’affichez rien, et passez un AbortSignal pour que les outils disparaissent lorsque le visiteur quitte la 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;
}

Ajoutez <SearchTool /> au layout ou à la page où l’outil a du sens. En développement, le Strict Mode de React exécute les effets deux fois, et le nettoyage ci-dessus gère ce cas.

Garder la logique dans une route API

L’outil n’est qu’une fine enveloppe. La validation, les limites et les permissions doivent rester sur le serveur, là où un visiteur ne peut pas les modifier :

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

Les formulaires comme outils

Pour un formulaire simple, ajoutez toolname et tooldescription à l’élément <form>. React transmet à la page ces attributs inconnus en minuscules. Le navigateur remplit le formulaire et, par défaut, c’est toujours le visiteur qui clique sur le bouton.

Règles de sécurité

• Commencez en lecture seule. La recherche et les détails d’abord ; signalez-les avec readOnlyHint.
• Demandez avant d’agir. Signalez les actions de panier, de réservation et de formulaire avec consequentialHint, pour que le visiteur confirme.
• Vérifiez côté serveur. Le navigateur n’est pas une barrière de sécurité : validez chaque paramètre et chaque permission dans votre backend.
• Renvoyez le minimum. N’envoyez que ce qu’un client a le droit de voir, jamais de données d’administration ni les informations d’autres clients.

Testez

1. Utilisez une version récente de Chrome avec WebMCP activé, via l’origin trial ou le flag de test.
2. Appelez chaque outil avec des paramètres valides et invalides.
3. Vérifiez que les visiteurs habituels ne voient aucune différence.
4. Lancez le vérificateur WebMCP gratuit sur la page précise où se trouvent vos outils.

Vous préférez nous le confier ?

Nous ajoutons WebMCP aux produits Next.js et React, de l’audit de préparation gratuit jusqu’aux outils testés. Découvrez nos services d’intégration WebMCP et notre offre de développement Next.js.