WebMCP

1. Introduction

WebMCP API is a new JavaScript interface that allows web developers to expose their web application functionality as “tools” - JavaScript functions with natural language descriptions and structured schemas that can be invoked by agents , browser’s agents , and assistive technologies . Web pages that use WebMCP can be thought of as Model Context Protocol [MCP] servers that implement tools in client-side script instead of on the backend. WebMCP enables collaborative workflows where users and agents work together within the same web interface, leveraging existing application logic while maintaining shared context and user control.

2. Terminology

An agent is an autonomous assistant that can understand a user’s goals and take actions on the user’s behalf to achieve them. Today, these are typically implemented by large language model (LLM) based AI platforms , interacting with users via text-based chat interfaces.

A browser’s agent is an agent provided by or through the browser that could be built directly into the browser or hosted by it, for example, via an extension or plug-in.

An AI platform is a provider of agentic assistants such as OpenAI’s ChatGPT, Anthropic’s Claude, or Google’s Gemini.

3. Supporting concepts

A model context is a struct with the following items :

tool map: a map whose keys are strings and whose values are tool definition structs .

A tool definition is a struct with the following items :

name

a string uniquely identifying a tool registered within a model context ’s tool map ; it is the same as the key identifying this object.

The name ’s length must be between 1 and 128, inclusive, and only consist of ASCII alphanumeric code points , U+005F LOW LINE (_), U+002D HYPHEN-MINUS (-), and U+002E FULL STOP (.).

title

A string -or-null representing a human-readable title of the tool for use in user interfaces.

Note: If title is not provided, the user agent is free to use a different value for display.

description

a string .

input schema

a string .

Note: For tools registered by the imperative form of this API (i.e., registerTool() ), this is the stringified representation of inputSchema. For tools registered declaratively , this will be a stringified JSON Schema object created by the synthesize a declarative JSON Schema object algorithm . [JSON-SCHEMA]

execute steps

a set of steps to invoke the tool.

Note: For tools registered imperatively, these steps will simply invoke the supplied ToolExecuteCallback callback. For tools registered declaratively , this will be a set of "internal" steps that have not been defined yet, that describe how to fill out a form and its form-associated elements .

read-only hint

a boolean , initially false.

To unregister a tool for a model context given a string tool name, run these steps:

Let tool map be the associated model context ’s tool map .
Assert tool map [ tool name ] exists .
Remove tool map [ tool name ].

4. API

4.1. Extensions to the `Navigator` Interface

The Navigator interface is extended to provide access to the ModelContext.

partial interface Navigator {
  [SecureContext, SameObject] readonly attribute ModelContext modelContext;
};

Each Navigator object has an associated modelContext , which is a ModelContext instance created alongside the Navigator.

The


modelContext

getter steps are to return this ’s modelContext .

4.2. ModelContext Interface

The ModelContext interface provides methods for web applications to register and manage tools that can be invoked by agents .

[Exposed=Window, SecureContext]
interface ModelContext {
  undefined registerTool(ModelContextTool tool, optional ModelContextRegisterToolOptions options = {});
};

Each ModelContext object has an associated internal context , which is a model context struct created alongside the ModelContext.

navigator . modelContext . registerTool(tool, options): Registers a tool that agents can invoke. Throws an exception if a tool with the same name is already registered, if the given name or description are empty strings, or if the inputSchema is invalid.

The


registerTool(

tool
,

options

)

method steps are:

Let tool map be this ’s internal context ’s tool map .
Let tool name be tool ’s name.
Let tool title be tool ’s title.
If tool map [ tool name ] exists , then throw an InvalidStateError DOMException.
If tool name or description is an empty string, then throw an InvalidStateError DOMException.
If either tool name is the empty string, or its length is greater than 128, or if tool name contains a code point that is not an ASCII alphanumeric , U+005F (_), U+002D (-), or U+002E (.), then throw an InvalidStateError.
Let stringified input schema be the empty string.
If tool ’s inputSchema exists , then set stringified input schema to the result of serializing a JavaScript value to a JSON string , given tool ’s inputSchema.
The serialization algorithm above throws exceptions in the following cases:
1. Throws a new TypeError when the backing " JSON.stringify() " yields undefined, e.g., " inputSchema: { toJSON() {return HTMLDivElement;}} ", or " inputSchema: { toJSON() {return undefined;}} ".
2. Re-throws exceptions thrown by " JSON.stringify() ", e.g., when " inputSchema " is an object with a circular reference, etc.
Let read-only hint be true if tool ’s annotations exists and its readOnlyHint is true. Otherwise, let it be false.
Let signal be options ’s signal.
If signal exists , then:
1. If signal is aborted , then optionally report a warning to the console indicating that the tool was not registered because the AbortSignal was already aborted , and return.
2. Add an abort algorithm to signal that unregisters a tool from this internal context given tool name.
Let tool definition be a new tool definition , with the following items :

name

tool name

title

tool title

description

tool ’s description

input schema

stringified input schema

execute steps

steps that invoke tool ’s execute

read-only hint

read-only hint
Set this ’s internal context [ tool name ] to tool definition.

4.2.1. ModelContextTool Dictionary

The ModelContextTool dictionary describes a tool that can be invoked by agents .

dictionary ModelContextTool {
  required DOMString name;
  // Because `title` is for display in possibly native UIs, this must be a `USVString`.
  // See https://w3ctag.github.io/design-principles/#idl-string-types.
  USVString title;
  required DOMString description;
  object inputSchema;
  required ToolExecuteCallback execute;
  ToolAnnotations annotations;
};
dictionary ToolAnnotations {
  boolean readOnlyHint = false;
};
callback ToolExecuteCallback = Promise<any> (object input, ModelContextClient client);

tool [" name "]

A unique identifier for the tool. This is used by agents to reference the tool when making tool calls.

tool [" title "]

A label for the tool. This is used by the user agent to reference the tool in the user interface.

It is recommended that this string be localized to the user’s language.

tool [" description "]

A natural language description of the tool’s functionality. This helps agents understand when and how to use the tool.

tool [" inputSchema "]

A JSON Schema [JSON-SCHEMA] object describing the expected input parameters for the tool.

tool [" execute "]

A callback function that is invoked when an agent calls the tool. The function receives the input parameters and a ModelContextClient object.

The function can be asynchronous and return a promise, in which case the agent will receive the result once the promise is resolved.

tool [" annotations "]

Optional annotations providing additional metadata about the tool’s behavior.

The ToolAnnotations dictionary provides optional metadata about a tool:

readOnlyHint , of type boolean , defaulting to false: If true, indicates that the tool does not modify any state and only reads data. This hint can help agents make decisions about when it is safe to call the tool.

4.2.2. ModelContextRegisterToolOptions Dictionary

The ModelContextRegisterToolOptions dictionary carries information pertaining to a tool’s registration, in contrast with the ModelContextTool dictionary which carries the tool definition itself.

dictionary ModelContextRegisterToolOptions {
  AbortSignal signal;
};

tool [" signal "]: An AbortSignal that unregisters the tool when aborted.

4.2.3. ModelContextClient Interface

The ModelContextClient interface represents an agent executing a tool provided by the site through the ModelContext API.

[Exposed=Window, SecureContext]
interface ModelContextClient {
  Promise<any> requestUserInteraction(UserInteractionCallback callback);
};
callback UserInteractionCallback = Promise<any> ();

client . requestUserInteraction(callback)

Asynchronously requests user input during the execution of a tool.

The callback function is invoked to perform the user interaction (e.g., showing a confirmation dialog), and the promise resolves with the result of the callback.

The


requestUserInteraction(

callback

)

method steps are:

TODO: fill this out.

4.3. Declarative WebMCP

This section is entirely a TODO. For now, refer to the explainer draft .

The synthesize a declarative JSON Schema object algorithm , given a



form

element form, runs the following steps. They return a map representing a JSON Schema object. [JSON-SCHEMA]

TODO: Derive a conformant JSON Schema object from form and its form-associated elements .

5. Interaction with agents

5.1. Event loop integration

A web site’s functionality is exposed to agents as tools that live in a Document ’s event loop , that get registered with the APIs in this specification.

The user agent ’s browser agent runs in parallel to any event loops associated with a ModelContext relevant global object . Steps running on the browser agent get queued on its AI agent queue , which is the result of starting a new parallel queue .

Conversely, steps queued from the browser agent onto the event loop of a given ModelContext object (i.e., the "main thread" where JavaScript runs) are queued on its relevant global object ’s AI task source .

5.2. Page observations

In-page agents implemented in JavaScript can "observe" the tools that a page offers by using the ModelContext APIs directly, and any other platform APIs to obtain necessary context about the page in order to actuate it appropriately.

The browser agent , on the other hand, does not run JavaScript on the page. Instead, it obtains a view of the page’s tools and any other relevant context by getting an observation . An observation is an implementation-defined data structure containing at least a tool map , which is a map whose keys are unique ID s, and whose values are tool definitions .

Note: An observation is usually a "snapshot" distillation of a page being presented to the user, along with any other state the user agent believes is relevant for the browser agent ; this often includes screenshots of the page, not just a DOM serialization. See Annotated Page Content (APC) in the Chromium project for an example of what might contribute to an observation.

To perform an observation given a top-level traversable traversable, run these steps:

Assert : This algorithm is running in the browser agent ’s AI agent queue .
Assert :traversable ’s active document is not fully active .
Let observation be a new observation .
Let flat descendants be the inclusive descendant navigables of traversable ’s active document .
For each navigable descendant of flat descendants:
1. Let document be descendant ’s active document ’s.
2. Let id be document ’s unique ID .
3. Set observation ’s tool map [ id ] = document ’s relevant global object ’s Navigator ’s modelContext ’s internal context ’s tool map ’s values , which are tool definitions .
Perform any implementation-defined steps to add anything to observation that the user agent might deem useful or necessary, besides just populating the tool map . This might include annotated screenshots of the page, parts of the accessibility tree, etc.
Perform any implementation-defined steps with observation and the browser agent , to expose the observation ’s tool map to the browser agent in whatever way it accepts.
Note: Despite the name of this API (i., Web MCP ), this specification does not prescribe the format in which tools are exposed to the browser agent . Browsers are free to distill and expose tools via Model Context Protocol, other proprietary "function calling" methods, or any other way it deems appropriate.
Implementations are expected to convey to the browser agent any relevant security information associated with tool definitions , such as the originating origin , among other things, so that the backing model has an idea of the different parties at play, and can most safely carry out the end user’s intent.

Each Document object has a unique ID , which is a unique internal value .

The times at which a browser agent performs an observation are implementation-defined . A browser agent may enqueue steps to the AI agent queue to perform an observation given any top-level browsing context in the user agent browsing context group set , at any time, although implementations typically reserve this operation for when the user is interacting with a browser agent while web content is in view.

6. Security and privacy considerations

6. 7. Accessibility considerations

7. 8. Acknowledgements

Thanks to Brandon Walderman, Leo Lee, Andrew Nolan, David Bokan, Khushal Sagar, Hannah Van Opstal, Sushanth Rajasankar for the initial explainer, proposals and discussions that established the foundation for this specification.

Also many thanks to Alex Nahas and Jason McGhee for sharing early implementation experience.

Finally, thanks to the participants of the Web Machine Learning Community Group for feedback and suggestions.

WebMCP

Abstract

Status of this document

1. Introduction

2. Terminology

3. Supporting concepts

4. API

4.1. Extensions to the `Navigator` Interface

4.2. ModelContext Interface

4.2.1. ModelContextTool Dictionary

4.2.2. ModelContextRegisterToolOptions Dictionary

4.2.3. ModelContextClient Interface

4.3. Declarative WebMCP

5. Interaction with agents

5.1. Event loop integration

5.2. Page observations

6. Security and privacy considerations

6. 7. Accessibility considerations

7. 8. Acknowledgements

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

WebMCP

Abstract

Status of this document

1. Introduction

2. Terminology

3. Supporting concepts

4. API

4.1. Extensions to the Navigator Interface

4.2. ModelContext Interface

4.2.1. ModelContextTool Dictionary

4.2.2. ModelContextRegisterToolOptions Dictionary

4.2.3. ModelContextClient Interface

4.3. Declarative WebMCP

5. Interaction with agents

5.1. Event loop integration

5.2. Page observations

6. Security and privacy considerations

6. 7. Accessibility considerations

7. 8. Acknowledgements

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

IDL Index

4.1. Extensions to the `Navigator` Interface