WebMCP and debuff: when pages hand agents tools

WebMCP is a proposed browser API that lets a web page give tools straight to the AI agent in your browser: no MCP server, no config file, no Node process. For game developers that means the game itself can tell an agent "here's how to read my state, press keys and take a screenshot". debuff already exposes those tools to agents like Claude Code over MCP. We've built a WebMCP version of them and tested it in Chrome Canary, and we'll ship it once browser agents start calling page tools. This post covers what WebMCP is, what it makes possible, and how debuff will use it.

What WebMCP is

Today an agent works with a web page in one of two ways. It reads the page like a person does (screenshots, the DOM, clicking on coordinates), or someone sets up an MCP server that drives the browser from outside. The first is slow and guesses. The second needs installing and configuring.

WebMCP adds a third: the page registers tools itself.

document.modelContext.registerTool({
  name: "game_state",
  description: "Current scene, tick and the scene's inspect() data.",
  annotations: { readOnlyHint: true, debugging: true },
  execute: async () => ({ content: [{ type: "text", text: JSON.stringify(state()) }] }),
});

A tool has a name, a description, a JSON Schema for its input and a function that runs it, the same shape as an MCP tool. The browser's agent sees the list and calls whichever tools fit the task. The page decides exactly what an agent may do, and each call runs page code instead of a guessed click.

The spec is a W3C Community Group draft. Chrome Canary has it behind a flag. It isn't on by default in any browser yet.

What it does for games

Games are a hard case for agents that read pages. A canvas is a wall of pixels, the state lives in JavaScript and everything moves 60 times a second. Screenshots can't tell an agent the player's velocity, and a click on coordinates can't hold a key for exactly 40 frames. Tools can do both.

With WebMCP, an agent in your browser can:

• Playtest the game you have open. Pause, step frame by frame, hold keys, read positions and take screenshots, on the exact tab you're looking at.
• Tune feel live. Read the game's tunable params and change jump height or run speed while you watch, then report numbers instead of impressions.
• Debug. Read runtime errors with their explanations, and the moments you flagged in the dev overlay.

All of that already works with debuff's MCP server, but it needs an MCP-capable agent set up in your editor or terminal. WebMCP moves the same tools into the page, so any browser agent gets them with zero setup.

How debuff will integrate it

1. Dev builds: your game's dev tools become agent tools

@debuffjp/dev will register the game's dev hooks as WebMCP tools whenever the browser supports it:

game_state, game_step, game_pause, game_input, game_command, game_params, game_set_param, game_capture, game_errors, game_notes

They use the same names and arguments as the debuff MCP server, so the agent skill and prompts carry over unchanged, and a test keeps the two in sync. The dev overlay will show a chip that lights up each time an agent calls a tool, so you can always see what the agent is actually doing.

This only runs in development. devTools() sits behind import.meta.env.DEV, so production bundles don't change, and devTools({ webmcp: false }) turns it off.

This part is built. In Canary 158 with the flag on, all 10 tools register, and a full playtest loop (read state, hold right for 600 frames, change run speed, capture) works through the browser's own executeTool. A 600-frame step takes about 400 ms in page on a laptop.

2. debuff.jp: docs and the playground

debuff.jp already runs an MCP server for agents. With WebMCP the site can offer the same tools in the page:

• Docs pages register search_docs, get_api and get_doc, so a browser agent gets exact API answers instead of scraping the page.
• The playground registers write_game, read_game, the game tools above and share_link. An agent in your browser could write a game, run it, look at it, fix it and hand you a link, with nothing installed.

3. Shipped games: maybe, and only opt-in

We're also thinking about a small production API that lets a game author choose a few safe actions to expose to agents, such as "start a new run", "what's my score" or "describe the screen". That could help with accessibility and QA on deployed builds. It also raises real questions about leaderboards and agents playing games for people, so it would be off by default, opt-in per game and tree-shaken when unused. We haven't decided on this one.

Safety

The dev tools give an agent nothing it couldn't already reach: anything that can call them could already call window.__DEBUFF_DEV__. They don't register for other origins, and none of them reaches outside the tab (the WebMCP screenshot can't write a file). Tools that return text a player or tester typed will set WebMCP's untrustedContentHint, so agents treat that text as data rather than instructions.

When

The page side is ready. What's missing is agents. In our tests neither Claude in Chrome nor Gemini in Chrome picked up page WebMCP tools by themselves yet. We'll ship the dev integration as soon as one does, and the docs and playground tools follow.

To follow along, or if you have an agent that already calls WebMCP tools, come and tell us in the debuff Discord.