Building for the WebMCP Challenge? Expose your real actions, not a chatbot

The WebMCP Challenge is live — OpenAI with Chrome, Cloudflare, Shopify, Vercel, Render, and Netlify, running Aug 25–Sep 3 on Devpost, with $35k in prizes. Ten days to build something with WebMCP: the browser API that lets a page hand AI agents real tools to call instead of making them click through your UI.

I maintain an open-source WebMCP tool (disclosed bias — link at the end), so I've watched a lot of these builds. The projects that demo cleanly and the ones that fall apart in front of an agent differ on exactly two things. If you're building this week, here they are.

1. Expose actions, not a chat box

The reflex is to register a chat or ask tool that wraps a search box. Don't. An agent already is the chat interface — it doesn't need another one. What it can't do is your site's actions: search your catalog, add to cart, check availability, book a slot, submit the form. Register those.

document.modelContext.registerTool({
  name: "search_catalog",
  description: "Search products in this store",
  inputSchema: {
    type: "object",
    properties: { q: { type: "string" } },
    required: ["q"],
  },
  async execute({ q }) {
    const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`);
    const items = await res.json();
    return {
      content: [{ type: "text", text: `${items.length} results for "${q}"` }],
      structuredContent: { items },
    };
  },
});

(The registration getter moved from navigator.modelContext to document.modelContext on Aug 10 — feature-detect both if you want to be safe, and gate on support so non-agentic browsers are unaffected.)

2. Your return value is a contract, not a UI

This is the one that fails demos. A human reads your page; an agent reads what your tool returns. So a tool that does its job and returns { ok: true } — or navigates the page and returns nothing — has told the agent nothing. The next step in the agent's plan has no data to act on, so it stalls or hallucinates.

Return the actual result as structuredContent: the items found, the new cart total, the booking confirmation number, the validation error. Treat every tool's return as an API contract you now owe the agent — because that's what it is.

Three failure modes to check before you record your demo:

• Success flags. { ok: true } from a search tool. Return the results instead.
• Stale reads. Returning cached state after an action mutated it. Return the post-action state.
• Untyped errors. Throwing a raw string. Return a structured error the agent can branch on.

What the hackathon won't grade — but production will

The Challenge grades a working demo. Two things it won't surface that bite the moment a real agent hits your site:

• Coverage drift. Every tool is hand-written and hand-maintained. The moment your UI changes and a tool doesn't, the agent calls a tool that lies. On a multi-page site this is most of the ongoing work.
• Observability. You have no idea which agent called which tool, in what order, or whether the call returned usable data. Today that's guesswork — and it's exactly what you'll want the day after you ship.

Neither is hard to reason about; both are easy to forget while racing a 10-day clock.

Shortcut for the "wrap my existing site" track

If your project is an existing site rather than a greenfield app, you don't have to hand-write a registerTool for every action. Latch is an MIT-licensed one-line script that auto-detects your search, cart, and forms and exposes them as WebMCP tools — handy when you want coverage fast and time is the constraint (source). Write them yourself if you want full control; either way, the two rules above still decide whether your demo works.

Good luck in the Challenge. Build the actions, honor the return contract, and your agent demo will do the thing on the first take.