How OpenAI’s WebMCP Lets Websites Expose Tools Directly to AI Agents

What WebMCP Is

WebMCP (Web Model Context Protocol) enables a website to declare its own AI‑callable capabilities in a /.well-known/webmcp.json manifest. An AI agent running in the browser discovers the manifest automatically and can invoke the declared tools via standard HTTPS REST calls, shifting tool registration from AI developers to website operators.

Technical Architecture and Workflow

The protocol follows four steps:

Discovery – the browser fetches /.well-known/webmcp.json from the site.

Negotiation – the agent reads the JSON‑Schema manifest to understand tool signatures and authentication requirements.

Invocation – the agent sends a REST request to the tool’s endpoint.

Response – the site returns JSON data that the agent consumes.

Manifest Schema Example

{
  "schema_version": "1.0",
  "provider": "example.com",
  "tools": [
    {
      "name": "search_papers",
      "description": "按关键词搜索论文并返回摘要列表",
      "endpoint": "/api/webmcp/search",
      "method": "POST",
      "parameters": {
        "query": {"type": "string", "required": true},
        "limit": {"type": "integer", "default": 10}
      }
    }
  ],
  "auth": {"type": "oauth2", "authorization_url": "/oauth/authorize"}
}

The manifest is served from the standard .well-known path, allowing cross‑site aggregation.

Key Differences from Anthropic MCP

Runtime location : Anthropic MCP runs in a local/remote server process; WebMCP relies on website‑side declaration and browser discovery.

Discovery mechanism : MCP requires manual server address configuration; WebMCP uses automatic .well-known discovery.

Transport protocol : MCP uses JSON‑RPC over stdio/SSE/streamable HTTP; WebMCP uses standard HTTPS REST.

Tool registration party : MCP tools are registered by AI application developers; WebMCP tools are registered by website operators.

Authentication model : MCP handles auth server‑side; WebMCP standardizes on OAuth2 or API‑Key.

Ecosystem positioning : MCP is a general tool‑connection layer; WebMCP is a web‑native tool exposure layer.

Chrome Extension Test (Codex Sidebar)

The Chrome extension, released in mid‑August, embeds the Codex agent in a persistent sidebar. After installation the sidebar detects a WebMCP manifest on the current page and displays an “Available Tools” list. Measured response times for tool invocation range from 1 s to 3 s, varying with network latency and target API speed. GPT‑4.1’s reasoning handles tool selection and parameter filling without difficulty.

In‑Depth Scenarios

Paper Analysis

On an arXiv page (which currently lacks a WebMCP manifest), the sidebar falls back to page‑content extraction plus long‑text analysis. Summarizing a 12‑page Transformer variant produced an ~800‑word structured abstract covering problem definition, methodological innovations, and experimental conclusions, with no obvious hallucinations. If the site provided a WebMCP manifest, the agent could call “fetch full text” and “extract figure data” directly, improving accuracy.

Image Understanding

On Unsplash, the sidebar invoked GPT‑4o’s vision capability to describe a complex scene (“a climber in a red jacket at dusk on a cliff edge with layered clouds”) and to identify composition techniques (“rule of thirds, subject at right‑hand golden ratio”).

Web Translation

Translating a Japanese technical blog to Chinese yielded context‑aware translations, e.g., rendering 「デプロイ」 as “publish” or “deploy” based on surrounding text. Translating a ~3000‑word article took about 8 seconds.

Notion Plugin Integration

Notion adopted WebMCP in August. When the sidebar is opened on a Notion page, tools such as “create page”, “query database”, and “update property” appear automatically. An instruction to “organize the current page’s to‑do items into a table with priority labels” resulted in a new table view within the same workspace, populated with extracted items and priority fields, using the existing OAuth login state without extra API tokens.

Developer Integration Guide

Create /.well-known/webmcp.json at the site root and define tools according to the schema.

Implement a REST endpoint for each tool; request and response bodies are plain JSON, identical to ordinary APIs.

Configure authentication. OAuth2 is recommended because the browser already holds the user’s login state, allowing the agent to reuse it without extra tokens.

Add appropriate CORS headers so the Chrome extension can make cross‑origin requests.

A typical backend developer can complete these steps in half a day to one day. OpenAI provides a validation utility webmcp-validator to check manifest compliance.

The manifest also supports a rate_limit field, enabling sites to declare per‑tool call frequency limits to mitigate abuse.

Open Issues

Security – how to handle malicious sites exposing harmful tools.

Privacy – data flow when an agent calls site APIs on behalf of a user.

Ecosystem fragmentation – potential competing standards from Google, Anthropic, etc.