API & agents

WebMCP.nl is zelf machine-leesbaar. Alle endpoints zijn CORS-open; lezen kan zonder auth, en schrijfacties verlopen via double opt-in (zie het beveiligingsmodel onderaan). Agents en developers kunnen ze direct gebruiken.

Probeer in Swagger →openapi.json

Register-API

De gepubliceerde bedrijfsvermeldingen, gesorteerd op technische scanscore. Betaalde plaatsing staat apart in partners.

# Gepubliceerde bedrijven (filter optioneel: ?branche=hotel)
curl https://webmcp.nl/api/register

Respons:

{
  "aantal": 9,
  "aanbieders": [
    {
      "naam": "Garage Van der Meer",
      "domein": "garage-vandermeer.nl",
      "branche": "garage",
      "brancheLabel": "Garages",
      "regio": "Flevoland",
      "score": 94,
      "tools": ["plan_afspraak"],
      "uitgelicht": false
    }
  ],
  "partners": []
}

Directe scan, leesbaar zonder JavaScript

Een AI-browser die alleen pagina's kan openen, kan de daadwerkelijk gemeten WebMCP.nl-score ophalen met een gewone GET. Er is geen POST-call, plugin, account of e-mailadres nodig. Open de scan van top.nl voor de gratis samenvatting met score, deelscores en meetmoment in de HTML, ook zonder JavaScript. Vervang top.nl door het gewenste domein. Dezelfde meting is beschikbaar als leesbare tekst of de openbare scansamenvatting.

# HTML-pagina: de score staat al in de serverrespons
curl "https://webmcp.nl/scan?site=top.nl"

# Leesbare tekst voor browsers en AI-assistenten
curl "https://webmcp.nl/api/scan/preview?website=top.nl&format=txt"

# Dezelfde meting als JSON (standaardformaat)
curl "https://webmcp.nl/api/scan/preview?website=top.nl"

website is verplicht en accepteert een domein of een http(s)-URL. We normaliseren naar de hostnaam en scannen het domein, niet een meegegeven subpagina. GET deelt de meting met /rapport/[domein], slaat niets op in de database en verstuurt geen e-mail. De cache wordt na een uur opnieuw gevalideerd; tijdens het verversen kan nog de eerdere meting worden teruggegeven. Het veld gemetenOp hoort bij de meting, niet bij het ophalen. Gebruik format=json voor expliciet JSON; zonder format wordt ook Accept: text/plain ondersteund.

De JSON-respons bevat:

• ok: true, voorlopig: true, domein en url (de gescande URL).
• totaalScore (0–100), niveau (LAAG, BASIS, GOED of HOOG), niveauLabel, interpretatie en categorieen: per categorie de sleutel, label, gewicht en score.
• bedrijfsprofiel: het korte basisprofiel met naam, dienst en regio uit de bronwebsite; ontbrekende waarden zijn null. Dit is geen onafhankelijke bedrijfsverificatie.
• gemetenOp (ISO-meetmoment), modelVersie, rapportUrl, methodiekUrl, bestelUrl en beperkingen.
• concurrentenToegang: beschikbaarheid van de optionele concurrentenpreview en, indien ingeschakeld, een tijdelijk toegangsticket en publieke verificatiesleutel.

Citeer de score met het meetmoment en de rapportlink. Dit is een voorlopige technische meting volgens onze methodiek. De rapportscan verifieert gevonden toolregistraties waar nodig in een browser; toolselectie, argumenten, veilige uitvoering en resultaatkwaliteit vragen een afzonderlijke Effectiveness-evaluatie. De gratis respons bevat geen toolnamen, detailbevindingen, broncitaten, prioriteiten of verbeterplan. Het volledige technische rapport en onderzoek bij zes AI-modellen zijn samen apart te bestellen. Ontbrekende zoekresultaten bewijzen evenmin dat WebMCP-tools of llms.txt ontbreken. Bij een scanfout is geen betrouwbare score beschikbaar.

POST en compatibiliteit

POST gebruikt dezelfde gecachte scan als GET en geeft dezelfde publieke samenvatting terug. Het verzoek verstuurt geen e-mail en registreert de oorspronkelijke interne meting best-effort in het scanbeheer, zonder tweede scan.

curl -X POST https://webmcp.nl/api/scan/preview \
  -H "content-type: application/json" \
  -d '{"website":"voorbeeld.nl"}'

/api/scan/preview-request is een compatibiliteitsalias en ondersteunt dezelfde GET- en POST-verzoeken. Gebruik voor nieuwe integraties /api/scan/preview.

MCP-endpoint (voor agents)

JSON-RPC 2.0 op /api/mcp, Model Context Protocol. Tools: scan_website, zoek_aanbieders, vraag_offertes_aan, vraag_scan_aan.

Waarom deze site béíde heeft: het MCP-endpoint bedient agents en integraties systeem-tot-systeem (altijd bereikbaar, ook zonder bezoeker); de WebMCP-tools hieronder bedienen agents in de browser, binnen de sessie van de bezoeker. Zelfde backend-logica, twee loketten.

Gebruik scan_website met alleen website voor een directe score. Deze lees-tool geeft dezelfde meting terug als de GET-preview, inclusief meetmoment, deelscores, basisprofiel en beperkingen. Er wordt geen e-mail verstuurd. Bij een scanfout bevat het toolresultaat isError: true en een foutmelding, zonder score. vraag_scan_aan is de afzonderlijke aanvraag voor een gratis scansamenvatting per e-mail na bevestiging.

curl -X POST https://webmcp.nl/api/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"scan_website","arguments":{"website":"top.nl"}}}'

In een browser met WebMCP is dezelfde tool scan_website beschikbaar via document.modelContext. De tool verwerkt het argumentwebsite rechtstreeks en werkt ook op pagina's zonder scanformulier.

curl -X POST https://webmcp.nl/api/mcp \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"zoek_aanbieders","arguments":{"branche":"garage"}}}'

Koppelen in een MCP-client (config):

{
  "mcpServers": {
    "webmcp-nl": {
      "type": "http",
      "url": "https://webmcp.nl/api/mcp"
    }
  }
}

Zelf een WebMCP-tool registreren

De kern van WebMCP: je site biedt een actie aan die een agent in de browser kan aanroepen.

// Actuele WebMCP API-root.
const mc = document.modelContext;
mc?.registerTool({
  name: "plan_afspraak",
  description: "Plan een afspraak. Retourneert bevestiging en tijdslot.",
  inputSchema: {
    type: "object",
    properties: {
      datum: { type: "string" },
      tijd: { type: "string" }
    },
    required: ["datum", "tijd"]
  },
  // Spec-annotaties, beide default false. readOnlyHint: true = de tool
  // muteert niets (agents mogen hem zonder extra bevestiging draaien);
  // untrustedContentHint: true = de output bevat externe of
  // gebruikerscontent en verdient extra argwaan (prompt injection).
  annotations: { readOnlyHint: false },
  async execute({ datum, tijd }) {
    const res = await fetch("/api/afspraak", {
      method: "POST",
      body: JSON.stringify({ datum, tijd })
    });
    return { content: [{ type: "text", text: await res.text() }] };
  }
});

Onderhoud je nog een Chrome 149-integratie? Behandel navigator.modelContext dan als expliciete legacy-compatibiliteit, niet als de primaire implementatie. De actuele Chrome-documentatie en WebMCP-draft gebruiken document.modelContext.

Geen idee waar te beginnen? Onze tool-generator schrijft een concept voor je.

Limieten & fouten

• Rate limit: per IP (scan-preview 8/min, register 5/min, MCP 30/min) → 429 Too Many Requests. De HTML-scan, GET, POST en scan_website delen het scanbudget. Respecteer de Retry-After-header; een MCP-scanfout geeft de status en retryAfter in het toolresultaat.
• 400 bij ongeldige invoer of een onveilig/privé doel (SSRF-guard).
• 502 als de scan de site niet kan ophalen of meten; er wordt dan geen score gegeven.
• Standaard application/json, UTF-8, CORS *. De GET-scan ondersteunt ook text/plain met format=txt.

Annoteer je tools: readOnlyHint en untrustedContentHint

De spec definieert twee toolannotaties, beide standaard false. readOnlyHint markeert tools die niets muteren; agents kunnen die zonder extra bevestigingsstap draaien. untrustedContentHint markeert tools waarvan de output externe of gebruikerscontent bevat, zodat een agent die niet als instructies behandelt (prompt injection). Chrome geeft de annotaties ook terug via getTools(). De AI-Ready Scan telt ze in de geverifieerde meting: hoeveel tools read-only zijn, hoeveel muterend, en of annotaties helemaal ontbreken.

Cross-origin tools: embedded apps & microfrontends

Sinds de spec-draft van 26 augustus 2026 is tool-sharing over origins heen geformaliseerd. Een tool uit een iframe is niet automatisch beschikbaar: de tools Permissions Policy (default allowlist self) én expliciete origin-exposure moeten allebei kloppen, en die exposure-check geldt ook voor executeTool. Toolmetadata draagt het registrerende origin en window mee, zodat een agent altijd weet van wie een tool is.

// Embedded widget (bijv. betaal- of boekingsmodule) stelt een tool
// beschikbaar aan de hoofdsite — en alleen aan die site:
document.modelContext.registerTool({ name: "start_betaling", /* ... */ }, {
  exposedTo: ["https://www.hoofdsite.nl"]  // parseerbare, trustworthy origins; geen wildcard
});

// De hoofdsite moet het iframe expliciet toestaan:
// <iframe src="https://widget.nl/betalen" allow="tools"></iframe>
// (plus een Permissions-Policy die 'tools' voor dat origin toestaat)

// En vraagt tools van benoemde origins op:
const tools = await document.modelContext.getTools({
  fromOrigins: ["https://widget.nl"]
});

Dit maakt WebMCP relevant voor portals, payment-widgets en microfrontends: elk deel van de pagina kan zijn eigen tools aanbieden, met een expliciete vertrouwensgrens ertussen. De AI-Ready Scan controleert hierop: een expliciete Permissions-Policy: tools, allow="tools" op iframes, begrensde exposedTo-origins, en te brede exposure als verbeterpunt.

Kanttekening bij de praktijk: ChatGPT Site Tools ondersteunt momenteel een subset van de WebMCP-API's — declaratieve API's en tools in iframes werken daar nog niet. Cross-origin tools zijn dus vandaag vooral relevant voor de Chrome/Edge-origin-trials; bouw ze als progressive enhancement.

Beveiligingsmodel: lezen publiek, schrijven bevestigd

Lees-tools (scan_website, zoek_aanbieders, register-API, scan-preview) zijn publiek en dragen de MCP-annotatie readOnlyHint. Schrijvende tools (vraag_scan_aan, vraag_offertes_aan) voeren nooit direct iets uit: elke aanroep stuurt een HMAC-ondertekende bevestigingslink (24 uur geldig) naar het opgegeven e-mailadres, en pas de eigenaar van dat adres zet de actie door. Daarbovenop: per-tool rate limits, idempotente bevestiging (een herklik levert geen tweede scan of dubbele leads op), SSRF-bescherming op doel-URL's en auditlogging van elke schrijfpoging en bevestiging.

Waarom zo streng? De WebMCP-spec besteedt expliciet aandacht aan tool poisoning, output injection, intent misrepresentation en privacy-lekkage, en prompt injection is in agent-systemen een onopgelost probleem. Een endpoint dat namens een willekeurig e-mailadres state-changing acties uitvoert, is precies het soort oppervlak dat daarbij misbruikt wordt. Human-in-the-loop-bevestiging is dezelfde eis die we bij implementaties voor klanten stellen, dus die passen we ook op onszelf toe.

Voor LLMs

• /llms.txt, beknopte gids
• /llms-full.txt, volledige kennisbasis