WebMCP in Next.js und React: KI-Agenten-Tools richtig registrieren

Wenn Ihr Produkt auf Next.js oder React läuft, passt WebMCP sehr gut: Ein Tool ist eine kleine Funktion, und die eigentliche Arbeit erledigen bereits Ihre API-Routen. Dieser Leitfaden zeigt ein sauberes Muster. Ist das Thema neu für Sie? Lesen Sie zuerst, was WebMCP ist.

Tools in einer Client Component registrieren

document.modelContext gibt es nur im Browser, deshalb gehört die Registrierung in useEffect. Rendern Sie nichts und übergeben Sie ein AbortSignal, damit die Tools verschwinden, wenn der Besucher die Seite verlässt:

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

Fügen Sie <SearchTool /> in das Layout oder die Seite ein, wo das Tool sinnvoll ist. Der Strict Mode von React führt Effects in der Entwicklung zweimal aus; die Aufräumfunktion oben fängt das ab.

Die Logik in einer API-Route halten

Das Tool ist nur eine dünne Hülle. Prüfungen, Limits und Berechtigungen gehören auf den Server, wo ein Besucher sie nicht ändern kann:

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

Formulare als Tools

Für ein einfaches Formular ergänzen Sie toolname und tooldescription im Element <form>. React gibt diese unbekannten, kleingeschriebenen Attribute an die Seite weiter. Der Browser füllt das Formular aus, und den Button klickt standardmäßig weiterhin der Besucher.

Sicherheitsregeln

• Starten Sie mit reinem Lesezugriff. Zuerst Suche und Details; kennzeichnen Sie diese mit readOnlyHint.
• Fragen Sie vor dem Handeln. Kennzeichnen Sie Warenkorb-, Buchungs- und Formularaktionen mit consequentialHint, damit der Besucher bestätigt.
• Prüfen Sie auf dem Server. Der Browser ist keine Sicherheitsgrenze. Prüfen Sie deshalb jede Eingabe und jede Berechtigung in Ihrem Backend.
• Geben Sie wenig zurück. Senden Sie nur, was ein Kunde sehen darf, niemals Admin-Daten oder Datensätze anderer Kunden.

Testen

1. Nutzen Sie ein aktuelles Chrome mit aktiviertem WebMCP, über den Origin Trial oder das Test-Flag.
2. Rufen Sie jedes Tool mit gültigen und ungültigen Eingaben auf.
3. Prüfen Sie, dass normale Besucher keine Änderung bemerken.
4. Prüfen Sie genau die Seite, auf der Ihre Tools liegen, mit dem kostenlosen WebMCP-Checker.

Sollen wir das für Sie übernehmen?

Wir bringen WebMCP in Next.js- und React-Produkte – vom kostenlosen Readiness-Check bis zu getesteten Tools. Sehen Sie sich unsere WebMCP-Integrationsservices und unsere Next.js-Entwicklung an.