How to Use WebMCP with JavaScript for AI-Ready Web Apps

WebMCP lets a website expose selected actions to AI agents through structured tools instead of forcing an agent to interpret buttons, menus, and page text. In this tutorial, you will build a small JavaScript example that registers a web action, describes its inputs, and makes that action available to compatible agents while keeping the actual business logic in your page.

What WebMCP changes for a JavaScript application

A traditional web page is designed around a human interaction model: a person reads the interface, chooses an option, fills out a form, and clicks a button. An AI agent has a different problem. It needs to discover what actions the page supports, understand the required inputs, and invoke the right operation without guessing from the visual interface. WebMCP addresses that gap by giving web applications a way to expose structured capabilities that an agent can call.

The important distinction is that WebMCP does not turn your whole website into an uncontrolled API. You decide which operations are exposed and describe what each operation expects. The browser remains responsible for running the page code, while the agent gets a machine-readable way to request an allowed action.

Start with a normal JavaScript function

The easiest way to understand the model is to begin with ordinary application logic. Suppose a shopping page has a function that adds a product to a cart. The function can already perform the real work: validate the product, update application state, and refresh the interface. WebMCP adds a tool-facing layer around that existing operation rather than requiring you to rewrite the application.

function addToCart(productId, quantity) {
  if (!productId || quantity < 1) {
    throw new Error("Invalid cart request");
  }

console.log(`Adding ${quantity} item(s) of ${productId}`);
}

This separation matters because the same business logic can continue to serve normal clicks and agent-driven requests. If your site already has a large JavaScript application, you can expose carefully selected operations without rebuilding the application's core behavior.

Define the action an agent can discover

A WebMCP tool needs more than a function name. An agent needs a description of what the action does and the shape of the information it must provide. Think of the tool definition as a contract: the website says what operation is available, which arguments are accepted, and what those arguments mean.

For example, an action called add_to_cart can describe a product identifier and a quantity. A clear description helps an agent choose the operation for the right task instead of trying to manipulate unrelated page controls.

const addToCartTool = {
name: "add_to_cart",
description: "Add a product to the shopping cart",
inputSchema: {
type: "object",
properties: {
productId: {
type: "string",
description: "The product identifier"
},
quantity: {
type: "integer",
minimum: 1,
description: "Number of units to add"
}
},
required: ["productId", "quantity"]
}
};

The exact WebMCP browser API and availability can change as the specification and implementations develop, so production code should be checked against the current browser documentation before deployment. The important programming principle remains stable: describe an explicit capability rather than asking an agent to infer how your interface works.

Connect the tool to your page logic

Once the action is described, connect its invocation to the function that already performs the operation. A useful implementation keeps validation close to the business operation, because a tool definition is not a substitute for application security or input checking.

async function handleAddToCart(input) {
const productId = input.productId;
const quantity = Number(input.quantity);

if (!productId || !Number.isInteger(quantity) || quantity < 1) {
throw new Error("Invalid product or quantity");
}

return addToCart(productId, quantity);
}

This is also where you should decide what the agent is allowed to do. Reading product information and adding an item to a cart are different capabilities from changing an account email address, deleting data, or submitting an irreversible payment. Expose only operations whose behavior you can validate and whose consequences are appropriate for agent invocation.

Keep human and agent actions on the same path

A common mistake is to create a completely separate implementation for AI requests. That makes the application harder to maintain because a normal button and an agent can eventually behave differently. Instead, both interaction paths should converge on the same validated application functions.

For example, a human clicking an Add to Cart button might execute addToCart(productId, 1), while the WebMCP handler passes an agent-supplied quantity into the same function. The interface differs, but the important rules remain in one place. This approach also makes testing easier because you can verify the business operation independently from the way it was triggered.

Validate everything the agent sends

Structured input is safer than asking an agent to simulate arbitrary clicks, but structured input is not automatically trustworthy. The agent can still supply a missing product identifier, an invalid quantity, or a value your application does not expect. Validate types, ranges, permissions, and application state before performing the requested operation.

There is another useful distinction for developers: validation answers whether an input is structurally acceptable, while authorization answers whether the current user is allowed to perform the operation. A valid request to delete an account can still be forbidden. Keep those checks in the same security boundary you would use for a normal application request.

Return results an agent can actually use

The result of a tool call should contain useful information rather than forcing the agent to inspect the page again. If adding an item succeeds, a concise structured result might include the product identifier, quantity, and updated cart count. If the operation fails, return an error that explains what went wrong without exposing sensitive internal information.

return {
success: true,
productId,
quantity,
cartItemCount: 3
};

This makes the interaction easier for an agent to continue. Instead of interpreting a visual toast notification such as “Added!”, it receives data that can directly support the next step in a task. That is one of the practical reasons to expose tools deliberately rather than simply making every page element agent-accessible.

Test the tool like an API, even though it runs in the browser

Before exposing a WebMCP action to users, test it with the same discipline you would apply to an application programming interface. Check missing fields, incorrect types, boundary values, duplicate requests, unavailable products, and failures in the underlying application logic. Then test a normal human interaction to make sure adding the agent-facing path has not changed existing behavior.

You should also test what happens when an agent requests an action in an unexpected sequence. For example, a tool that confirms an order should not assume that an address, inventory reservation, or payment authorization already exists simply because the agent supplied an order identifier. The page should verify the actual application state before carrying out consequential operations.

Choose tools around tasks, not individual buttons

The most useful WebMCP design is usually not a one-to-one copy of every button on the page. A page might contain dozens of interface controls but only a handful of meaningful tasks. Group related operations around what a user is actually trying to accomplish, while keeping each tool narrow enough that its inputs and consequences are clear.

For example, a support dashboard could expose a tool for finding an open ticket and another for adding a reply, rather than exposing every table control and navigation button. This gives an agent a smaller, more understandable set of capabilities and gives the developer a clearer boundary around what automation is permitted to do.

What to check before putting WebMCP into production

WebMCP is most useful when the underlying application is already well structured. Before exposing tools, make sure your JavaScript functions have clear inputs and outputs, validation is centralized, sensitive operations have authorization checks, and failures produce understandable results. If the application relies heavily on hidden UI state or button-specific behavior, refactoring that logic first will usually make the WebMCP integration simpler.

It is also worth remembering that WebMCP is an emerging browser capability rather than a reason to abandon conventional APIs. If an operation needs server-side authorization, background processing, persistent access, or integration with systems outside the page, a conventional backend API may still be the appropriate mechanism. WebMCP is most interesting when an agent needs to work with capabilities that are already available through the web application itself.

The next step is to take one safe, useful action from an existing JavaScript application and expose only that capability. Once the input contract, validation, result format, and permission boundary are clear, expanding to additional agent-facing tools becomes a controlled application-design exercise rather than a rewrite of the website.