Gepubliceerd: 18 mei 2026, Laatste update: 16 november 2026
| Uitlegvideo | Web | Extensies | Chrome-status | Intentie |
|---|---|---|---|---|
| GitHub | Bekijken | Intent to Experiment |
Je kunt de WebMCP Imperative API gebruiken om veel soorten tools te definiëren met standaard JavaScript. Je tools kunnen verschillende functies uitvoeren, zoals formulierinvoer, sitenavigatie en statusbeheer.
Lees meer over gebruiksvoorbeelden voordat je deze API gebruikt.
Modelcontext geven
Gebruik de modelContext-interface om tools te registreren. Voor toolregistratie zijn een naam, beschrijving en invoerschema met relevante eigenschappen vereist.
Gebruik registerTool om één tool toe te voegen aan de modelcontext.
WebMCPza Maker
await document.modelContext.registerTool({
name: 'toggle_layer',
description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
inputSchema: {
type: 'object',
properties: {
layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
},
required: ['layer'],
},
execute: async ({ layer, action }) => {
await toggleLayer(layer, action);
return `Performed ${action || 'toggle'} on layer: ${layer}`;
},
});
Bestelstatus ophalen
await document.modelContext.registerTool({
name: 'get_order_status',
description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
inputSchema: {
"type": "object",
"properties": {
"timeframe": { "type": "string", "oneOf": [
{ "type": "string", "const": "today", "title": "Today" },
{ "type": "string", "const": "yesterday", "title": "Yesterday" },
{ "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
{ "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
{ "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
"enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
"description": "Timeframe for the order lookup." }
},
"required": [ "timeframe" ]
},
execute: async ({ timeframe }) => {
// Add your API or database logic here to fetch and return the order data as a string.
},
});
Uitvoerschema (optioneel)
Vanaf Chrome 159 kun je een outputSchema-property definiëren wanneer je een tool registreert om het verwachte JSON-schema van de retourwaarde te declareren.
Als je outputSchema definieert:
- Scheid intentie van structuur: Houd
descriptionbeknopt. Richt je op wat de tool doet en wanneer je deze moet aanroepen. Geef exacte propertynamen, -typen en koppelings-ID's aan inoutputSchemain plaats van ze te vermelden indescription. - Gebruik
outputSchemaselectief: VoegoutputSchematoe aan geconsolideerde lees- of zoektools met meerdere velden en tools die ID's retourneren voor downstream chaining. Laat deze weg bij beperkte leesacties met duidelijke uitvoer, muterende acties of UI-navigatietools om prompttokens te besparen. - Houd
execute()afgestemd opoutputSchema: Retourneer een JSON-serialiseerbare waarde die overeenkomt metoutputSchema. Agents kunnen resultaten valideren aan de hand van dit schema en een toolfout retourneren naar het model als een resultaat niet overeenkomt.
await document.modelContext.registerTool({
name: "getWeather",
description: "Returns the current weather for a city.",
inputSchema: {
type: "object",
properties: { city: { type: "string" } },
required: ["city"]
},
outputSchema: {
type: "object",
properties: {
temperature: { type: "number" },
conditions: { type: "string" }
},
required: ["temperature", "conditions"]
},
async execute({ city }) { /* ... */ }
});
Ga naar de voorbeeldextensie van WebMCP voor een voorbeeld van hoe een agent toolresultaten kan valideren met outputSchema.
Toolannotaties (optioneel)
Als je een tool registreert, kun je metadata toevoegen aan de property annotations.
Deze annotaties helpen agents en browsers de veiligheidskenmerken, verwachte bijwerkingen, betrouwbaarheid van de uitvoer en de beoogde doelgroep van een tool te begrijpen:
readOnlyHint(Booleaans, standaard ingesteld opfalse): Als deze parameter is ingesteld optrue, geeft dit aan dat de tool alleen informatie leest en de status van de app of het systeem niet wijzigt (bijvoorbeeld een productcatalogus doorzoeken of de bestelstatus ophalen). Zo kunnen agents bepalen of de tool veilig kan worden aangeroepen zonder bijwerkingen.untrustedContentHint(boolean, standaard ingesteld opfalse): Alstrue, geeft dit aan dat de uitvoer van de tool niet-vertrouwde gegevens bevat vanuit het perspectief van de auteur van de tool (bijvoorbeeld content van gebruikers, reviews of externe webgegevens). Dit geeft aan de agent en de client aan dat de geretourneerde payload een strengere beveiligingsafhandeling vereist, zoals opschoning of afbakening, om indirecte promptinjectie te beperken.consequentialHint(booleaans, standaard ingesteld opfalse): Alstrue, geeft dit aan dat de uitvoering van de tool leidt tot significante, echte of onomkeerbare acties (bijvoorbeeld een vlucht boeken, geld overmaken of gegevens verwijderen). Zo kunnen agents en browsers verplichte bevestigingsprompts voor gebruikers afdwingen voordat ze tools met een hoog risico uitvoeren. Dit vermindert het risico op onbedoelde of schadelijke verkeerde voorstelling van de gebruikersintentie.debugging(Booleaans, standaard ingesteld opfalse, beschikbaar vanaf Chrome 156): Als deze waardetrueis, geeft dit aan dat de tool specifiek is ontworpen voor inspectie- en tools voor ontwikkelaars (bijvoorbeeld testframeworks of AI-ondersteuning van Chrome DevTools) in plaats van interacties met eindgebruikers. Zo kunnen agents voor algemene doeleinden en eindgebruikers tools voor ontwikkelaars wegfilteren.
await document.modelContext.registerTool({
name: 'book_flight',
description: 'Book a flight for the user with confirmed flight details.',
inputSchema: {
type: 'object',
properties: {
flightId: { type: 'string', description: 'ID of the flight to book' },
passengers: { type: 'number', description: 'Number of tickets to purchase' },
},
required: ['flightId', 'passengers'],
},
annotations: {
readOnlyHint: false,
consequentialHint: true,
untrustedContentHint: false,
debugging: false,
},
execute: async ({ flightId, passengers }) => {
// Add your flight booking transaction logic here.
return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
},
});
Ga naar de voorbeeldextensie van WebMCP voor voorbeelden van hoe annotaties het gedrag van de agent kunnen beïnvloeden.
Registratie van tools ongedaan maken
Je kunt een tool verwijderen met AbortSignal als deze wordt doorgegeven als optionele parameter.
const addTodoTool = {
name: "addTodo",
description: "Add a new item to the to-do list",
inputSchema: {
type: "object",
properties: { text: { type: "string" } },
},
execute: async ({ text }) => {
// You should handle the persistence logic here (omitted for demo)
return `Added to-do: ${text}`;
},
annotations: {
readOnlyHint: false,
untrustedContentHint: true
},
};
const controller = new AbortController();
await document.modelContext.registerTool(addTodoTool, { signal: controller.signal });
// Unregister the tool later...
controller.abort();
Vanaf Chrome 153 kun je de registratie van een tool ongedaan maken zonder lopende uitvoeringen te annuleren en te onderbreken. Zo voorkom je onverwachte bijwerkingen als je de levenscycli van tools beheert in componentframeworks.
Omgaan met annulering van tool
De functie execute krijgt een AbortSignal-parameter met de naam signal als 2e argument om annuleringen van de uitvoering die door de gebruiker of agent zijn gestart, op een goede manier af te handelen. Als je dit signaal doorgeeft aan langdurige asynchrone taken of netwerkbewerkingen (zoals fetch()), voorkom je onnodig werk, verbeter je het algemene resourcebeheer en voorkom je mogelijke lekken.
await document.modelContext.registerTool({
name: 'fetch_tool',
description: 'Fetch the text content of a URL and stream the response.',
inputSchema: {
type: 'object',
properties: {
url: { type: 'string', description: 'The URL to fetch' },
priority: { type: 'string', enum: ['high', 'low', 'auto'] },
},
required: ['url'],
},
execute: async ({ url, priority }, { signal }) => {
// Abort the fetch request when tool execution is aborted.
const response = await fetch(url, { priority, signal });
const stream = response.body.pipeThrough(new TextDecoderStream());
for await (const chunk of stream) {
document.querySelector('pre').textContent += chunk;
}
return 'Success';
},
});
Tools ontdekken
Gebruik document.modelContext.getTools() om beschikbare tools op te halen. Deze asynchrone methode retourneert een alfabetisch geordende lijst met tools waartoe het aanroepende document toegang heeft.
const [tool] = await document.modelContext.getTools();
console.log(tool);
// {
// annotations: { consequentialHint: false, debugging: false, readOnlyHint: false, untrustedContentHint: true }, // Optional hints
// description: "Add a new item to the to-do list",
// inputSchema: {"type":"object","properties":{…}},
// name: "addTodo",
// origin: "https://example.com",
// title: ""
// window: Window {window: Window, self: Window, …},
// }
Standaard retourneert getTools() alleen tools met dezelfde oorsprong die zijn geregistreerd door het aanroepende document of andere documenten met dezelfde oorsprong in de framestructuur. Als je cross-origin tools wilt ophalen, moet je de oorsprongen expliciet vermelden in de optie fromOrigins. Deze matrix ondersteunt alleen beveiligde herkomsten.
Tools uit cross-origin documenten worden alleen opgenomen als:
- De hostingbron staat in de optie
fromOrigins. - De tool is expliciet blootgesteld aan je oorsprong.
// https://example.com
// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();
// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
fromOrigins: ['https://partner.org']
});
Bekijk de demo van de WebMCP Page Agent voor een voorbeeld van hoe je tools ophaalt uit een iframe en ze uitvoert in een online chatinterface. Ga naar de voorbeeldextensie van WebMCP om te zien hoe een agent in een browserextensie tools vindt en uitvoert in same-origin en cross-origin iframes.
Tool uitvoeren
Als je een tool die in getTools() is gevonden handmatig wilt uitvoeren, roep je document.modelContext.executeTool() aan met een optioneel JavaScript-object voor invoerargumenten dat kan worden geserialiseerd naar een json-tekenreeks. Deze asynchrone methode
retourneert het resultaat van de uitvoering van de tool of null als er een navigatie wordt geactiveerd.
const result = await document.modelContext.executeTool(tool, { text: "Buy milk" });
console.log(result);
// 'Added to-do: Buy milk'
Je kunt een tooluitvoering in behandeling annuleren met AbortSignal als deze wordt doorgegeven als een optionele parameter.
const controller = new AbortController();
document.modelContext.executeTool(tool, { text: "Buy milk" }, { signal: controller.signal });
// Cancel tool execution later...
controller.abort();
Evenementen
Frames kunnen luisteren naar de gebeurtenis toolchange op document.modelContext om een melding te krijgen als de lijst met beschikbare tools is gewijzigd.
document.modelContext.addEventListener("toolchange", (event) => {
// Tools have changed.
});
Cross-origin iframes
WebMCP ondersteunt cross-origin iframes die zowel beleid voor rechten als expliciete oorsprongspoorten gebruiken.
Beleid voor rechten
Toolregistratie staat standaard uit in cross-origin iframes. Een pagina moet toegang delegeren via het tools
Beleid voor rechten:
<iframe src="https://example.com" allow="tools"></iframe>
Blootstelling aan oorsprong
Tools zijn standaard niet beschikbaar voor cross-origin-documenten. Je kunt de array exposedTo binnen registerTool gebruiken om specifieke oorsprongen te vermelden die een tool mogen bekijken en uitvoeren. Deze matrix ondersteunt alleen beveiligde herkomsten.
// https://partner.org
await document.modelContext.registerTool({
name: 'my_shared_tool',
description: 'Shared across origins',
// ...
}, {
exposedTo: ['https://example.com']
});
Ondersteuning in veelgebruikte JavaScript-frameworks
React, Angular en Vue hebben experimentele ondersteuning voor WebMCP.
- React: Gebruik het pakket
use-webmcp-tool. Registreer tools met de hookuseWebMCPdie is gekoppeld aan de levenscyclus van het koppelen en ontkoppelen van je component. Deze hook ondersteunt voorwaardelijke toolregistratie en normaliseert automatisch de uitvoeringsresultaten. - Angular: Registreer tools die zijn gekoppeld aan de levenscyclus van de dependency injection van de app en zet je Signal-formulieren om in WebMCP-tools.
- Vue: Gebruik de samenstelbare
useWebMCPuit het pakket@vueuse/core. Registreer tools die zijn gekoppeld aan de huidige levenscyclus van het Vue-bereik. De implementatie van Vue ondersteunt reactieve en voorwaardelijke toolregistratie en normaliseert automatisch de uitvoeringsresultaten.
Betrokkenheid en feedback delen
WebMCP wordt actief besproken en kan in de toekomst worden gewijzigd. Als je deze API probeert en feedback hebt, horen we dat graag.
- Lees de uitleg over WebMCP, stel vragen en neem deel aan de discussie.
- Lees hoe je effectieve WebMCP-tools maakt en best practices voor WebMCP.
- Controleer de implementatie voor Chrome op Chrome-status.
- Neem deel aan het programma voor vroege preview voor een vroege blik op nieuwe API's en toegang tot onze mailinglijst.
- Als je feedback hebt over de implementatie van Chrome, dien je een Chromium-bug in.