What WebMCP is

The problem with reading the screen

An agent can operate a web application the way a person new to it would: read the page, find a button that looks right, click it, and read the page again. It works often enough to be impressive and fails often enough to be useless for anything that matters.

It guesses at intent from labels. It breaks when you redesign. And it cannot tell a button that saves from a button that deletes, because nothing on the screen says which is which in a way a program can rely on.

A page that says what it can do

WebMCP is an open way for a web page to declare its operations instead. Your page registers each one as a tool: a name, a description written for an agent, a schema for its inputs, hints about its behaviour, and a function that does the work. An agent running your page calls the operation directly.

This is a fragment of the smallest example in this section:

document.modelContext.registerTool({
  name: "say_hello",
  description: "Greet a person by name on this page " +
    "and return the greeting.",
  inputSchema: { /* one required string, "name" */ },
  annotations: { readOnlyHint: true },
  execute: async ({ name }) => { /* … */ }
});

The function runs in your page, with your page’s code and your page’s session. The agent never sees your markup or your internals — only the name, the description, the schema, and what execute returns.

What the agent sees, and what the person sees

The agent sees your tools’ names, descriptions and schemas, and chooses among them the way it chooses among any tools: by reading. That is why the description is the most important thing you write.

The person sees a question before anything runs — naming your site and what it publishes — and answers it as narrowly or as widely as they like. Your hints decide what they are asked: a tool that only reads is a smaller question than one that deletes.

Where it runs

In the person’s browser, in their signed-in session on your site. There is no API key to issue, no server to deploy and secure, and nothing for the person to install for your site in particular: the operations your users can already perform become operations an agent can perform for them, with their permissions and nothing more.

XataWorks is a desktop application whose built-in browser runs WebMCP pages, and it is where every example in this section is tested. Think of it as a bus: each web application that declares its tools plugs into it, and an agent can work every application plugged in, together. The bus is that idea at length.

Two places to register, two shapes of call

The current draft of the standard puts the registry on document.modelContext; an earlier draft put it on navigator.modelContext. XataWorks accepts both. It also accepts the object form shown above, a positional form (registerTool(name, description, inputSchema, execute)), and provideContext({ tools }) for registering several at once. This section uses the object form on document.modelContext throughout.

The host matters in one way you should know about: a tool that declares no hints is treated as one that changes things when it was registered on document.modelContext, and as consequential when it was registered on navigator.modelContext. Declare your hints and the question goes away — see safety classes.

Where to go next

• Hello, WebMCP — a working tool in one page, tested in XataWorks.
• WebMCP and MCP — how this differs from the MCP you may already know.
• The bus — why plugging in is worth more than one integration.