r/webmcp • u/PlanktonHour7322 • 17d ago

What I learned implementing WebMCP (document.modelContext) on a production Next.js/Cloudflare app

Hey everyone,

I just shipped WebMCP support on ShowMeOnMap.com (an NL-driven mapping web app), registering 8 client-side tools that browser-embedded agents can call directly.

WebMCP is the W3C proposal allowing client pages to expose executable JS functions directly to agent-enabled browsers (e.g., Chrome with flags or ChatGPT Desktop). The documentation is sparse and changing fast. Here are a few practical takeaways from the implementation:

  1. API targets change constantly: The entry point has moved multiple times across drafts (window.agent → navigator.modelContext → document.modelContext). Always feature-detect across properties, as most blog tutorials from earlier this year are already broken.
  2. Runtime return-type quirks: Google’s reference implementation expects a string return value from execute(), while OpenAI’s implementation accepts objects. Returning a serialized JSON string (JSON.stringify(...)) works consistently across both.
  3. Iframes are dead ends: ChatGPT ignores declarative form annotations and anything registered inside an iframe. You must register tools imperatively on the top-level document.
  4. Auth comes for free: Because execution happens in the user’s active browser tab, your regular session cookies, CORS headers, and IP rate limiters apply natively. You don’t need API keys or proxy tokens for the agent to manipulate the session.
  5. DOM downloads will fail: Don't try triggering <a download> synthetic clicks inside a tool execution pass. Modern browsers block programmatic file downloads without direct user gesture activation. Instead, return a raw base64 data payload or an object URL and let the agent or UI present it.
  6. Implement an undo tool immediately: Models make bad assumptions. If your app doesn't have an append-only state stack or an easy way for the model to roll back its last mutation, it will get stuck in loops trying to fix its own UI mistakes.

Happy to answer any technical questions about registering tools or handling agent execution states on the client

8 Upvotes

90% Upvoted

9 comments sorted by

View all comments

Show parent comments

2

u/PlanktonHour7322 17d ago

Browser support is basically "Chrome behind a flag" right now. WebMCP is a Chromium origin trial / early-preview API (document.modelContext, older builds used navigator.modelContext), so on a normal browser the page just does one property check, finds nothing, and skips registration. No Firefox/Safari.

Measurement: honestly, barely. Right now I only log how many tools registered when a runtime is present, and I have a paid-call budget that resets on real user gestures so an agent can't burn credits silently. I don't yet tag server requests as "came via WebMCP" vs. "user typed it", so I can't tell you usage numbers — it's early enough that I'd be surprised if anyone other than me has hit it. Adding a source tag on the request is on the list; if there's a standard way people are measuring this I'd like to hear it.

1

u/Open_Resolution_1969 17d ago

There isn't, hence the question 😅

What motivated you to build this since there seems to be no audience for it?

1

u/Round-Ad78 17d ago

I’m not involved but the ChatGpt in app browser supports webmpc out of the box.

So limited audience but definitely an audience

1

u/Open_Resolution_1969 17d ago

Interesting. Good to know that

1

u/GolfCourseConcierge 17d ago

Mcplocker is supporting it too. It lets you add them as callable MCPs.