WebMCP Proposal

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. Security and privacy considerations

4. Accessibility considerations

5. API

5.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;
};

5.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 provideContext(optional ModelContextOptions options = {});
  undefined clearContext();
  undefined registerTool(ModelContextTool tool);
  undefined unregisterTool(DOMString name);
};

navigator.modelContext.provideContext(options)

Registers the provided context (tools) with the browser. This method clears any pre-existing tools and other context before registering the new ones.

navigator.modelContext.clearContext()

Unregisters all context (tools) with the browser.

navigator.modelContext.registerTool(tool)

Registers a single tool without clearing the existing set of tools. The method throws an error, if a tool with the same name already exists, or if the inputSchema is invalid.

navigator.modelContext.unregisterTool(name)

Removes the tool with the specified name from the registered set.

5.2.1. ModelContextOptions Dictionary

dictionary ModelContextOptions {
  sequence<ModelContextTool> tools = [];
};

options["tools"]

A list of tools to register with the browser. Each tool name in the list is expected to be unique.

5.2.2. ModelContextTool Dictionary

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

dictionary ModelContextTool {
  required DOMString name;
  required DOMString description;
  object inputSchema;
  required ToolExecuteCallback execute;
  ToolAnnotations annotations;
};

dictionary ToolAnnotations {
  boolean readOnlyHint;
};

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["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:

annotations["readOnlyHint"]

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.

5.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.

6. 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.