Title: WebMCP
Shortname: webmcp
Level: None
Status: CG-DRAFT
Group: webml
Repository: webmachinelearning/webmcp
URL: https://webmachinelearning.github.io/webmcp
Editor: Brandon Walderman, Microsoft https://www.microsoft.com, brwalder@microsoft.com, w3cid 115877
Editor: Khushal Sagar, Google https://www.google.com, khushalsagar@google.com, w3cid 122787
Editor: Dominic Farolino, Google https://www.google.com, domfarolino@google.com, w3cid 102763
Abstract: The WebMCP API enables web applications to provide JavaScript-based tools to AI agents.
Markup Shorthands: markdown yes, css no
Complain About: accidental-2119 yes, missing-example-ids yes
Assume Explicit For: yes
Default Biblio Status: current
Boilerplate: omit conformance
Indent: 2
Die On: warning
Test Suite: https://wpt.fyi/results/webmcp

spec:html; type:dfn;
  text:browsing context group set
  text:unique internal value
spec: webidl; type: dfn;
  text: an exception was thrown

spec: html; urlPrefix: https://html.spec.whatwg.org/C
  type: dfn
    text: browsing context group
spec: SECURE-CONTEXTS; urlPrefix: https://w3c.github.io/webappsec-secure-contexts/
  type: abstract-op
    text: is origin potentially trustworthy?; url: is-origin-trustworthy
spec: ECMASCRIPT; urlPrefix: https://tc39.es/ecma262/
  type: dfn
    text: is an object; url: sec-object-type

{
  "mcp": {
    "href": "https://modelcontextprotocol.io/specification/latest",
    "title": "Model Context Protocol (MCP) Specification",
    "publisher": "The Linux Foundation"
  },
  "json-schema": {
    "href": "https://json-schema.org/draft/2020-12/json-schema-core.html",
    "title": "JSON Schema: A Media Type for Describing JSON Documents",
    "publisher": "JSON Schema"
  },
  "spotlighting": {
    "href": "https://arxiv.org/abs/2403.14720",
    "title": "Defending Against Indirect Prompt Injection Attacks With Spotlighting",
    "publisher": "arXiv"
  },
  "sockpuppetting": {
    "href": "https://arxiv.org/abs/2601.13359",
    "title": "Sockpuppetting: Jailbreaking LLMs by Combining Prefilling with Optimization",
    "publisher": "arXiv"
  }
}

Introduction

Terminology

Supporting concepts

: tool map :: a [=map=] whose [=map/keys=] are [=strings=] and whose [=map/values=] are [=tool definition=] [=structs=]. : local pending tool executions map :: a [=map=] whose [=map/keys=] are [=unique internal values=] and whose [=map/values=] are [=local pending tool execution=] [=structs=]. It is initially empty. Note: this map is similar to a [=traversable navigable=]'s [=traversable navigable/pending tool executions map=], but it only contains pending execution information for tools under a single {{ModelContext}} object. It is used to store objects that can only be accessed from that object's event loop, and because it is event-loop-local, it can get out of sync from the [=traversable navigable=]'s more "global" map.

: name :: a [=string=] uniquely identifying a tool registered within a [=model context=]'s [=model context/tool map=]; it is the same as the [=map/key=] identifying this object. The [=tool definition/name=]'s [=string/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 {{ModelContextTool/title}} is not provided, the user agent is free to use a different value for display. : description :: a [=string=]. : input schema :: a [=string=]. Note: This is the stringified representation of the {{ModelContextTool/inputSchema}} passed to {{ModelContext/registerTool()}}. [[!JSON-SCHEMA]] : execute steps :: an algorithm that takes a {{Document}} targetDocument, a [=string=] inputArguments, an algorithm completionSteps that takes a [=string=]-or-null and a [=tool execution error=]-or-null, and a [=unique internal value=] uuid. Note: These steps [=invoke the execute callback=] of the {{ModelContextTool}} passed to {{ModelContext/registerTool()}}. : annotations :: an [=annotations=]-or-null. : exposed origins :: a [=list=] of [=origins=], initially [=list/empty=].

: abort controller :: an {{AbortController}}.

: read-only hint :: a [=boolean=], initially false. : untrusted content hint :: a [=boolean=], initially false. : consequential hint :: a [=boolean=], initially false. : debugging :: a [=boolean=], initially false.

Pending tool executions

: caller document :: a {{Document}}. : target document :: a {{Document}}. : tool name :: a [=string=]. : completion steps :: an algorithm that takes a [=string=]-or-null and a [=tool execution error=]-or-null.

API

Extensions to {{Document}}

ModelContext Interface

document.{{Document/modelContext}}.{{ModelContext/registerTool(tool, options)}}

Registers a tool that [=agents=] can invoke. Returns a rejected promise if a tool with the same name is already registered, if the given {{ModelContextTool/name}} or {{ModelContextTool/description}} are empty strings, or if the {{ModelContextTool/inputSchema}} is invalid.

document.{{Document/modelContext}}.{{ModelContext/getTools(options)}}

Returns a promise that resolves to a list of registered tools from this document and its descendants that are exposed to this document. This API is designed for so-called "in-page" agents written in JavaScript, and possibly living in <{iframe}>s. The [=user agent=]'s [=browser agent=] uses a different internal mechanism to retrieve the tools exposed to it.

document.{{Document/modelContext}}.{{ModelContext/executeTool(tool, inputObject, options)}}

Executes a tool on the document it was registered on. Returns a promise that resolves to the stringified result of the tool's execution.

tool is a {{RegisteredTool}}, often retrieved by {{ModelContext/getTools()}}. Callers pass a JavaScript object in as the {{ModelContext/executeTool(tool)/inputObject}} argument for the tool; it's expected to match the schema described by the tool's {{RegisteredTool/inputSchema}}. If the argument is omitted, the tool receives an empty object.

ModelContextTool Dictionary

tool["{{ModelContextTool/name}}"]

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

tool["{{ModelContextTool/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 {{NavigatorLanguage/language}}.

tool["{{ModelContextTool/description}}"]

A natural language description of the tool's functionality. This helps [=agents=] understand when and how to use the tool.

tool["{{ModelContextTool/inputSchema}}"]

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

tool["{{ModelContextTool/execute}}"]

A callback function that is invoked when an [=agent=] calls the tool. The function receives the input parameters and execution options.

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

tool["{{ModelContextTool/annotations}}"]

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

: annotations["{{ToolAnnotations/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. : annotations["{{ToolAnnotations/untrustedContentHint}}"] :: If true, indicates that the tool's output contains data that is untrusted, from the perspective of the author registering the tool. : annotations["{{ToolAnnotations/consequentialHint}}"] :: If true, indicates that executing the tool will result in consequential actions that are significant, real-world, or non-reversible, ex: booking a flight, transferring money. : annotations["{{ToolAnnotations/debugging}}"] :: If true, indicates that the tool is intended for debugging and developer tooling rather than end-user interactions.

ToolExecuteCallbackOptions Dictionary

: options["{{ToolExecuteCallbackOptions/signal}}"] :: An {{AbortSignal}} that communicates when the execution of the tool has been cancelled.

ModelContextRegisterToolOptions Dictionary

: options["{{ModelContextRegisterToolOptions/exposedTo}}"] :: An array of origins that control which documents this tool is exposed to, in the current document's tree. : options["{{ModelContextRegisterToolOptions/signal}}"] :: An {{AbortSignal}} that unregisters the tool when aborted.

ModelContextGetToolOptions Dictionary

: options["{{ModelContextGetToolOptions/fromOrigins}}"] :: An array of origins from which to query tools. Documents whose origin appears in this list, or are same-origin with the caller, have their tools queried. An empty list only includes same-origin documents.

ModelContextExecuteToolOptions Dictionary

: options["{{ModelContextExecuteToolOptions/signal}}"] :: An {{AbortSignal}} that can be used to cancel the execution of the tool.

RegisteredTool Dictionary

: tool["{{RegisteredTool/name}}"] :: A unique identifier for the tool. It is the same value provided at tool registration, via {{ModelContextTool/name}}. : tool["{{RegisteredTool/title}}"] :: A human-readable label for the tool. It is the same value provided at tool registration, via {{ModelContextTool/title}}. : tool["{{RegisteredTool/description}}"] :: A natural language description of the tool's functionality. It is the same value provided at tool registration, via {{ModelContextTool/description}}. : tool["{{RegisteredTool/inputSchema}}"] :: A JSON Schema object describing the expected input parameters for the tool [[!JSON-SCHEMA]]. It is a deep copy of the schema provided at tool registration, via {{ModelContextTool/inputSchema}}. : tool["{{RegisteredTool/window}}"] :: The {{Window}} of the document that registered the tool. : tool["{{RegisteredTool/origin}}"] :: The origin of the document that registered the tool. This member is only meaningful when the tool is cross-origin, and the consumer of a tool cannot otherwise get the tool's origin from its {{RegisteredTool/window}}. For same-origin tools, this is the same as the tool's {{RegisteredTool/window}}'s {{WindowOrWorkerGlobalScope/origin}}, and the caller's own {{Window}}.{{WindowOrWorkerGlobalScope/origin}}. : tool["{{RegisteredTool/annotations}}"] :: Optional annotations providing metadata about the tool. It matches {{ModelContextTool/annotations}}.

Events

ToolActivatedEvent Interface

: toolName :: Returns the name of the tool whose execution has started.

ToolCancelEvent Interface

: toolName :: Returns the name of the tool whose execution was cancelled.

Permissions policy integration

Interaction with agents

Event loop integration

Page observations

: origin :: an [=origin=]. Note: While exposure of tools to the [=browser agent=] is [=implementation-defined=], [=user agents=] are expected to include the origin field to avoid confusion that could be exploited by an attacker. : tools :: a [=list=] of [=tool definition=] [=structs=].

Security and Privacy Considerations

Approach to Risk Assessment and Mitigations

1. All entities involved: we will take into account the roles and responsibilities of:
   • Site authors
   • [=Agent=] providers
   • [=User agents=]
   • End-users
2. Limitations and responsibilities: This document cannot define precise mitigation strategies that [=agents=] or [=user agents=] must provide. Instead, we will:
   • Clearly define the responsibilities for each system
   • Document common mitigations as recommendations for [=agents=] and [=user agents=]
   • Explore these mitigations to inform additions to the WebMCP API
3. Alignment with MCP: we will adopt relevant risk assessments and mitigations from MCP [[MCP]] to inform discussions in WebMCP.

Agent Baseline Capabilities

• Identity inheritance: [=Agents=] are able to inherit user identity and authentication context from the browser. When an [=agent=] visits a website, it carries the user's logged-in credentials and session state.
• Extended user context: [=Agents=] are able to access personalization data, browsing history, payment information, and other sensitive user data to improve task completion.
• Cross-site context: [=Agents=] are able to access and correlate information across multiple websites to fulfill user requests.

Key Security and Privacy Risks

Prompt Injection Attacks

• Agent decision-making relies on natural language interpretation
• Tool descriptions and return values could be treated as trusted context by [=agents=]
• Natural language is inherently ambiguous and difficult to sanitize

Metadata / Description Attacks (Tool Poisoning)

• Threat Actor: Malicious websites implementing WebMCP tools
• Target: The agent's subsequent reasoning and actions
• Assets at Risk:
  • Information carried by the agent (user data, cross-site context)
  • Control of the agent's behavior and decisions
  • Other websites the agent may interact with

Output Injection Attacks

• Threat Actors:
  • Malicious websites creating WebMCP tools
  • Malicious actors influencing website content (e.g., untrusted user-generated content on social media platforms, forums, review sites)
• Target: The agent's subsequent reasoning and actions
• Assets at Risk:
  • Information carried by the agent (user data, cross-site context)
  • Control of the agent's behavior and decisions
  • Other websites the agent may interact with

Tool Implementation as Attack Targets

• Threat Actor: Malicious actors who gain control of [=agents=] with access to WebMCP tools
• Target: Websites implementing valuable or sensitive WebMCP tools
• Assets at Risk:
  • High-value actions exposed by the tool (e.g., database access, transactions)

Misrepresentation of Intent

Why This Matters

• Make purchases
• Transfer funds
• Modify account settings
• Share private data with third parties
• Delete user content

Misalignment Types

1. Malicious misrepresentation (fraud):
   • Deliberate deception to trick [=agents=] into performing unauthorized actions.
   • The goal is to create tools that explicitly deflect blame or misattribute actions to [=agents=].
   • This involves making the [=agents=] intentionally take a harmful action which can be attributed to the [=agent=].
2. Accidental misalignment and/or ambiguity:
   • Poorly written descriptions, outdated documentation, or inherent imprecision in natural language.
   • Side effects not mentioned in the description.

Scenario: Ambiguous Finalization (Accidental or Malicious)

Current Gaps

• No verification mechanism: Agent implementers cannot verify that tool implementations match their descriptions
• Semantic ambiguity: Natural language descriptions are subjective and open to interpretation
• No behavioral contracts: Unlike typed APIs, tool behaviors cannot be statically analyzed or verified
• Agent trust assumptions: [=Agents=] must assume good faith from site developers

Privacy Leakage Through Over-Parameterization

The Privacy Risk

• User personalization data
• Browsing history
• Cross-site information
• Inferred or stored user attributes

Example Attack

1. [=Agent=] sees reasonable-sounding parameter descriptions
2. [=Agent=] has access to this user information through personalization APIs
3. [=Agent=] helpfully provides all requested parameters
4. Site is now able to log all parameters to build user profile

Implications

• Silent profiling: Sites build detailed user profiles without explicit data sharing consent
• Cross-site tracking and context leakage: [=Agents=] could have built the above-mentioned personalization context from multiple websites. For example, learning a current location from a weather site and revealing it to another site through tool parameters, enabling cross-site tracking.
• Discrimination risk: Extracted attributes (age, pregnancy status, location) could be used for price discrimination or biased service

Violation of Same-Origin Boundaries

TODO: Document risks and implications of [=agents=] carrying state from one origin to another. Detail how tools executed on one origin may carry state from another origin, potentially leading to data leakage or same-origin policy bypasses if not handled securely by the [=user agent=]. This section should probably talk about the WebMCP permissions policy and other cross-origin opt in mechanisms.

Interaction with Private Browsing Modes

Mitigations

Disabling WebMCP with Permissions Policy

Restricting maximum input lengths

Supporting interoperable probabilistic defense structures through shared attack eval datasets

Untrusted Annotation for Tool Responses

Consequential Annotation for Tool Executions

Accessibility considerations

Acknowledgements