DEV Community: Razvan

WebMCP: A new contract between AI agents and websites

Razvan — Tue, 03 Mar 2026 16:06:18 +0000

🚨 Update on WebMCP: the API shape is already evolving.
Starting in Chrome 147.0.7721.0, provideContext() and clearContext() are being removed in favor of a more secure, additive model.

To prevent malicious scripts from "hijacking" user-agent interactions.

To align with standard web API patterns like addEventListener.

You've probably already heard of MCP from Anthropic, the protocol bridging the gap between AI and our data. Now Google is taking that idea one step further, bringing it directly into the browser. Meet WebMCP.

If you've watched an AI agent trying to interact with a website, you've probably seen it scraping the entire DOM, downloading a dump of the entire HTML page, taking screenshots, and only after that understanding what it can do. This operation takes time and it's a waste of precious tokens.

WebMCP is proposing a new way for developers to define a public interface for their website that AI agents can discover and use to interact with it. This is definitely quicker and cheaper.

I built a small shopping cart demo to explore the proposed APIs. You can find it here.

What is WebMCP, exactly?

The core idea is that a website can publish a structured contract (a set of named tools with explicit schemas) that any AI agent can discover and use reliably. Instead of the agent reverse-engineering your UI, your site simply says: "Here are the things you can do, and here's exactly how to do them."

The spec defines three pillars:

Discovery: a standard way for agents to query which tools a page exposes
Schemas: explicit input/output definitions
State: a shared understanding of what's currently available on the page

Think of it as an MCP server, but baked into the browser and tied directly to the page's live DOM.

⚠️ Availability

WebMCP is an experimental proposed standard behind a Chrome flag. If you want to play with it, you need:

Chrome: Version 146.0.7672.0 or higher

Flags: The "WebMCP for testing" flag must be enabled (chrome://flags/#enable-webmcp-testing)

ℹ️ To inspect registered functions, execute them manually or test them with an agent, install the Model Context Tool Inspector Chrome extension.

Two APIs, two philosophies

WebMCP offers two complementary ways to expose tools.

The Imperative API

The Imperative API is JavaScript-first approach. You register tools programmatically via window.navigator.modelContext, giving each one a name, a description, a JSON Schema for its inputs, and an execute function that runs when an agent calls it.

window.navigator.modelContext.registerTool({
  name: "addToCart",
  description: "Add a product to the shopping cart",
  inputSchema: {
    type: "object",
    properties: {
      product_id: { type: "string" },
      quantity:   { type: "number" }
    },
    required: ["product_id"]
  },
  execute: ({ product_id, quantity }) => {
    // your logic here
    return { content: [{ type: "text", text: `Added ${quantity}x ${product_id}` }] };
  }
});

registerTool registers a single tool without touching the others. When you need to register multiple tools at once, provideContext is the right call:

window.navigator.modelContext.provideContext({
  tools: [
    {
      name: "getCart",
      // ...
    },
    // ...
  ],
});

‼️ Watch out: provideContext replaces ALL registered tools — including declarative ones.

This is a subtle but important gotcha. When you call provideContext, it doesn't just add tools, it wipes out the entire existing set and replaces it. This includes any tools the browser has already registered from your declarative HTML forms.

There is already an open discussion about this function and it looks like the developers are not very happy about this API.

If you need to remove a specific tool at any point, you can use unregisterTool:

window.navigator.modelContext.unregisterTool("addTodo");

The Declarative API

The Declarative API takes a different approach: rather than writing JavaScript, you annotate your existing HTML forms with a small set of custom attributes and let the browser do the heavy lifting.

<form
  toolname="applyCoupon"
  tooldescription="Apply a discount coupon code to the cart"
  id="coupon-form"
>
  <label for="coupon_code">Coupon Code</label>
  <input
    type="text"
    id="coupon_code"
    name="coupon_code"
    placeholder="e.g. SAVE10"
    toolparamtitle="Coupon Code"
    toolparamdescription="A valid discount coupon code"
  />
  <button type="submit">Apply Coupon</button>
</form>

The browser reads these annotations at parse time and internally constructs the same JSON Schema that the Imperative API produces manually. When an agent invokes the tool, the browser focuses the form, populates the fields and, if toolautosubmit is set submits it automatically without requiring user interaction.

The attributes available are:

toolname: the registered name of the tool that the AI agent can call
tooldescription: human readable description of what the tool does
toolautosubmit: lets the AI agent submit the form automatically
toolparamtitle: maps to the JSON Schema property key. If omitted, the browser defaults to the input element's name
toolparamdescription: maps to the property description within the JSON Schema. If omitted, the browser uses the text content of the associated <label> element, or the aria-description if no label exists

Knowing when an agent is in charge

The SubmitEvent introduces a new agentInvoked boolean attribute. This lets you understand who triggered the action, the agent or the user and adapt your app's behaviour accordingly.

Additionally, SubmitEvent now includes a respondWith(Promise<any>) method which lets you pass a promise to the browser that resolves with the form's result data. That value is then serialized and returned to the model as the tool's output. You must first call preventDefault() to stop the browser's standard form submission.

form.addEventListener("submit", (e) => {
  e.preventDefault();
  const result = doTheWork();
  if (e.agentInvoked) {
    e.respondWith(Promise.resolve(result));
  }
});

Visual feedback

There are also CSS pseudo-classes for visual feedback when an agent is interacting with a form: :tool-form-active is applied to the form itself, and :tool-submit-active to its submit button. These are useful for showing the user that an agent is in control. Pair them with the toolactivated and toolcancel window events to hook into the full tool lifecycle:

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`${toolName} was activated by an agent`);
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`${toolName} was cancelled`);
});

ℹ️ Practical note: you must serve over HTTP

Opening an HTML file directly via file:// will silently fail — window.navigator.modelContext simply won't initialize. This is a standard browser security boundary, not a WebMCP bug. Any local server works: npx http-server, python3 -m http.server 3000, or npx vite.

Conclusion

AI agents are increasingly the ones interacting with the software we build, but our websites were never designed for them. Web scraping and visual UI parsing are fragile, slow, and expensive in tokens. WebMCP could solve this by letting us define a clear, explicit contract between our website and any agent that wants to interact with it, without rewriting everything from scratch. The Declarative API in particular is compelling precisely because it progressively enhances forms that already exist.

It's still an experimental proposed standard, but the core idea is solid. I hope it sees the light soon.

Bridging the Gap: A Deep Dive into the Model Context Protocol (MCP)

Razvan — Thu, 05 Feb 2026 07:32:36 +0000

In the rapidly evolving world of AI, Large Language Models (LLMs) are only as powerful as the data they can access and the tools they can use. Historically, connecting an AI application to a local database or a specific API required custom, bespoke integration or a lot of manual copy-pasting.

That changed at the end of 2024, when Anthropic released the Model Context Protocol (MCP) specification. MCP is an open-source standard for connecting AI to external systems, whether it’s browsing local files, querying a database, or triggering complex workflows.

Let’s start with the basics.

What is MCP?

At its core, MCP is an open-source standard that enables AI applications like ChatGPT or Claude to access data sources, tools, and workflows. By providing a unified bridge between the model and the “outside world,” MCP gives AI "superpowers", moving it beyond a simple chat interface and offering users infinite possibilities.

The Architecture: Host, Client, and Server

The architecture is elegantly simple, following a client-server model. Applications like VS Code or Claude Desktop are the MCP Host and connects to a local or remote program that exposes data or functionality, the MCP Server. The MCP Client is a dedicated connection within the host for every specific server.

One of my first experiments was connecting Jira to GitHub Copilot on VSCode (the Host). When VSCode connects to the Jira MCP server, it instantiates an MCP client object to maintain that specific connection. If I then connect to my local filesystem, VSCode simply instantiates additional client objects for those connections.

The Two-Layer System

The protocol is split into two distinct layers to handle communication:

The Data Layer: Defines what is being said. Based on JSON-RPC, it handles the connection lifecycle and core primitives (tools, resources, and prompts).
The Transport Layer: Defines how the message gets there.

Stdio Transport: Used for local processes on the same machine (e.g., VSCode talking to your local files). It’s lightning-fast with zero network overhead.
Streamable HTTP Transport: Used for remote servers (e.g., the official Jira MCP server running on the Atlassian platform). It uses HTTP POST and Server-Sent Events (SSE) and supports secure authentication like OAuth.

The Building Blocks

Core Primitives

Once your host is connected to a server, the AI can interact with three main "primitives":

Tools (Executable Functions): The AI can actually do things.
- Example: create_issue creates a Jira ticket; add_comment updates a task.
Resources (Data Sources): These provide the context the AI needs.
- Example: Project Schemas help the AI understand that "Priority Highest" means "Blocker" while User Profiles help it map names to IDs.
Prompts (Templates): Reusable instructions that structure the interaction.
- Example: A "Bug Reporter" Prompt can force the AI to ask for "Steps to Reproduce" before it is allowed to create a ticket.

Server-to-Client Primitives: A Two-Way Street

MCP isn't just a one-way street. Servers can also request help from the Client:

Sampling: A server can ask the AI Host to complete a task. For instance, a Jira server could say: "Hey, use your language skills to summarise these 10 tickets into a release note paragraph for me."
Elicitation: This allows a server to ask the user for missing info. If the AI tries to create a ticket but doesn't know the project, the server triggers a request: "Which project should this ticket go into?"
Logging: Enables servers to send debug messages to the client for easy monitoring.

Staying Sync

In a dynamic environment, tools and data sources change constantly. MCP handles this through notification system: using JSON-RPC 2.0, a server can "push" updates to the client without waiting for a request.

📖 JSON-RPC (JavaScript Object Notation-Remote Procedure Call) is a JSON-based wire protocol for remote procedure calls (RPC). JSON-RPC allows for notifications (data sent to the server that does not require a response) and for multiple calls to be sent to the server which may be answered asynchronously.

For more information about JSON-RPC specification click here.

The Notification system is a very important component of the MCP architecture. The client doesn't have to keep asking "Is there anything new?", it just waits to be told. If a database goes offline or a new tool becomes available, the AI knows instantly.

Conclusion

As LLMs become more powerful, their utility depends on context. The MCP specification provides a standardised way to provide that context, making our lives easier. By standardising how models access information and execute tasks, MCP is paving the way for AI tools that are more integrated, more capable, and easier to build than ever before.

PS: More and more companies are releasing official MCP servers every day. You can explore the most popular ones on the official Anthropic MCP Gallery.