Making your site AI-agent ready through WebMCP requires three things: a tool architecture that maps your site’s capabilities, JavaScript implementation using navigator.modelContext, and a testing pipeline to validate agent interactions. This guide walks through each step with code examples and decision frameworks so your engineering team can start building today.
WebMCP was published as a W3C draft community group report on February 10, 2026. Chrome 146 Canary supports it behind the “WebMCP for testing” flag. If you haven’t read the fundamentals yet, start with our WebMCP explainer and come back here for implementation details.
“We’ve implemented WebMCP on 8 client sites since March 2026. The biggest lesson: don’t think of it as ‘adding an API to your site.’ Think of it as designing the agent’s experience the same way you design the user’s experience. What can the agent do? What does it need to know? What should it confirm before acting?”
Hardik Shah, Founder of ScaleGrowth.Digital
How do you plan your WebMCP tool architecture?
Before writing any code, map every user task your website supports. Open your analytics. Look at the top 20 conversion paths. Each completed action (purchase, booking, form submission, comparison, calculation) is a candidate for a WebMCP tool.
For each candidate, answer these questions:
- Can this task be completed with structured inputs? (If yes, it’s a strong candidate)
- Does it require visual interpretation? (If yes, it’s a weak candidate)
- Does it involve sensitive data or money? (If yes, it needs a confirmation step)
- Does it require authentication? (If yes, you need to handle session context)
Group your tools into tiers:
Tier 1 (Implement first): Read-only tools with no authentication. Product search, price lookup, availability check, feature comparison. These are low-risk, high-value, and let you test the pipeline without worrying about security.
Tier 2 (Implement second): Write actions with confirmation. Add to cart, schedule appointment, submit inquiry form. These modify state and should require user confirmation through the WebMCP permission system.
Tier 3 (Implement carefully): Transactional tools. Purchase, booking, payment. These involve money and need full authentication, confirmation flows, and strong error handling.
What does a basic WebMCP implementation look like?
Here’s a complete, minimal implementation for a service business that wants to expose appointment scheduling:
// Check for WebMCP support
if ('modelContext' in navigator) {
navigator.modelContext.exposeTools([
{
name: "getAvailableSlots",
description: "Check available appointment slots for a given date and service type",
parameters: {
date: {
type: "string",
format: "YYYY-MM-DD",
required: true,
description: "Date to check availability"
},
serviceType: {
type: "string",
enum: ["consultation", "audit", "workshop"],
required: true,
description: "Type of service"
}
},
handler: async ({ date, serviceType }) => {
const response = await fetch(
`/api/availability?date=${date}&service=${serviceType}`
);
return await response.json();
}
},
{
name: "bookAppointment",
description: "Book an appointment for a specific slot",
requiresConfirmation: true,
parameters: {
slotId: { type: "string", required: true },
name: { type: "string", required: true },
email: { type: "string", format: "email", required: true },
phone: { type: "string" },
notes: { type: "string" }
},
handler: async (params) => {
const response = await fetch('/api/appointments', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(params)
});
return await response.json();
}
}
]);
}Key implementation details in this example:
- Feature detection with
'modelContext' in navigatorensures the code doesn’t break in browsers without WebMCP support - Parameter types and descriptions help the agent understand what to send
- The
requiresConfirmation: trueflag on the booking tool triggers user confirmation before the action executes - The
enumtype constrains valid options, preventing agent guessing - Handlers call your existing API endpoints, so WebMCP sits on top of your current backend
How do you handle authentication in WebMCP?
Many valuable tools require knowing who the user is. The WebMCP spec handles this through the browser’s existing authentication context. If the user is logged in to your site, the agent’s tool calls carry the same session cookies.
For tools that require authentication but the user might not be logged in, use a two-step pattern:
{
name: "getOrderStatus",
description: "Check the status of an existing order",
requiresAuth: true,
authFlow: "redirect",
parameters: {
orderId: { type: "string", required: true }
},
handler: async ({ orderId }) => {
// Browser handles auth redirect if needed
const response = await fetch(`/api/orders/${orderId}`, {
credentials: 'include'
});
if (response.status === 401) {
return { error: "authentication_required", loginUrl: "/login" };
}
return await response.json();
}
}The agent receives the authentication error, can inform the user that login is needed, and can even initiate the login flow if the user consents. The spec is still evolving on exactly how this handoff works, so keep your auth flows simple until the specification stabilizes.
How do you test WebMCP implementations?
Testing requires Chrome 146 Canary with the WebMCP flag enabled. Here’s the process:
Step 1: Enable the flag. Open Chrome Canary, work through to chrome://flags, search for “WebMCP,” enable “WebMCP for testing,” and restart the browser.
Step 2: Verify tool registration. Open your page, open DevTools console, and run navigator.modelContext.getTools(). You should see your tool definitions returned as a structured array. If not, check for JavaScript errors in the console.
Step 3: Test individual tools. Call each tool manually from the console:
const tools = await navigator.modelContext.getTools();
const searchTool = tools.find(t => t.name === 'searchProducts');
const result = await searchTool.call({ query: "running shoes", maxPrice: 5000 });
console.log(result);Step 4: Test with an AI agent. As of March 2026, no major AI agent (ChatGPT, Gemini, Claude) has shipped production WebMCP support. For testing, we use a custom test use that simulates agent behavior: it reads the tool manifest, selects tools based on a user query, constructs parameters, and calls functions. We’ve open-sourced this use; contact us for the repository link.
Step 5: Error handling. Test every failure mode. What happens if the API returns a 500? If parameters are malformed? If the user isn’t authenticated? If the agent sends a type that doesn’t match the parameter definition? Each failure should return a clear error message the agent can interpret and communicate to the user.
What are the common implementation mistakes?
We’ve seen these across our first 8 implementations. Save yourself the debugging time.
Vague tool descriptions. “Process order” doesn’t tell the agent enough. “Complete a purchase for items in the user’s cart using the specified payment method” does. Agents select tools based on descriptions. If the description is ambiguous, the agent picks the wrong tool or skips yours entirely.
Missing parameter constraints. If a parameter only accepts certain values, use enum. If it needs a specific format, define format. Agents will send whatever seems reasonable. Without constraints, you get “March 25th” when you expected “2026-03-25” and your API breaks.
No graceful degradation. If WebMCP isn’t supported (which is most browsers today), your site must work normally. Wrap all WebMCP code in feature detection checks. Never let WebMCP JavaScript break the standard user experience.
Exposing too many tools. Start with 3-5 tools. An agent presented with 50 tools has to evaluate each one against the user’s request. Fewer, well-described tools get selected more accurately than a large menu of ambiguous ones. You can always add more later.
No monitoring. Once you deploy, you need to know which tools agents call, which parameters they send, which calls fail, and why. Build logging into every tool handler from day one. This data will be invaluable when agent traffic increases.
What should you implement first?
For most websites, start with these 3 tools:
- Search/discover: Whatever your primary catalog or listing function is. Product search, property search, service finder. This is the most commonly requested agent action.
- Get details: Detailed information about a specific item. Product specs, property details, service pricing. The agent will call search first, then get details on the results.
- Contact/inquiry: A structured way for the agent to submit a lead or inquiry on the user’s behalf. This converts agent traffic into pipeline.
These three tools cover the core agent workflow: find, learn, act. You can add cart, booking, and payment tools later as the spec matures and browser support broadens.
Our WebMCP implementation service handles the full pipeline: architecture design, development, testing, deployment, and monitoring setup. If you’d rather build in-house, this guide gives you the foundation. For an architecture review or a free readiness assessment, reach out to our engineering team.
The implementation window is now. Browser stable support is 4-6 months away. Brands that have tested, refined, and optimized their tool architecture by then will capture AI-driven transactions from day one. Everyone else will be starting from scratch while traffic is already flowing.