WebMCP Proposal

Source: Hacker News

Introduction {#intro}

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 [#agent]
• browser agents [#browsers-agent]
• assistive technologies (WAI‑ARIA)

Web pages that use WebMCP can be thought of as Model Context Protocol (MCP) servers [#biblio-mcp] that implement tools in client‑side script instead of on the back‑end. 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.

Terminology {#terminology}

• Agent – An autonomous assistant that can understand a user’s goals and take actions on the user’s behalf to achieve them. Today, agents are typically implemented by large‑language‑model (LLM) based AI platforms, interacting with users via text‑based chat interfaces.
• Browser’s agent – An agent provided by or through the browser. It may be built directly into the browser or hosted by it (e.g., via an extension or plug‑in).
• AI platform – A provider of agentic assistants, such as OpenAI’s ChatGPT, Anthropic’s Claude, or Google’s Gemini.

Security and privacy considerations

Content to be added.

Accessibility considerations {#accessibility}

Content to be added.

API

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

---

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

Methods

Algorithm steps (place‑holders)

provideContext(options)

TODO: fill this out.

clearContext()

TODO: fill this out.

registerTool(tool)

TODO: fill this out.

unregisterTool(name)

TODO: fill this out.

---

ModelContextOptions Dictionary

dictionary ModelContextOptions {
  sequence tools = [];
};

• options["tools"] – A list of tools to register with the browser. Each tool name in the list is expected to be unique.

---

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(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 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; the agent will receive the result once the promise is resolved.
• tool["annotations"] – Optional annotations providing additional metadata about the tool’s behavior.

ToolAnnotations Dictionary (metadata)

• annotations["readOnlyHint"] – If true, indicates that the tool does not modify any state and only reads data. This hint can help agents decide when it is safe to invoke the tool.

ModelContextClient Interface {#model-context-client}

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

Exposed: Window
SecureContext

interface ModelContextClient {
  Promise requestUserInteraction(
    UserInteractionCallback callback
  );
};

Callback Definition

callback UserInteractionCallback = Promise ();

Usage

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).
• The returned promise resolves with the result of the callback.

Method Steps

TODO: fill this out.

Acknowledgements {#acknowledgements}

Thanks to the following people for the initial explainer, proposals, and discussions that established the foundation for this specification:

• Brandon Walderman
• Leo Lee
• Andrew Nolan
• David Bokan
• Khushal Sagar
• Hannah Van Opstal
• Sushanth Rajasankar

Special 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 their feedback and suggestions.