Introduction

The problem

People are already pointing agents at the sites they use. Today those agents read your HTML and guess which control does what. WebMCP is the browser's answer: your page can register a small set of typed tools that an agent calls directly, in the signed-in user's session.

Somebody has to write those tools. Hand-writing a registerTool() call per action, a name, a description, a JSON Schema, an execute function, is a chore for one endpoint and a project nobody starts for seventy. And the details matter more than they look: a tool's description is part of the prompt the agent reasons over, and its schema is the contract the agent fills in. Hand-written copies of what your code already knows drift, and drift means the agent calls the wrong thing.

What webmcp-stack does

You already have the source of truth: an OpenAPI spec, or the validation schemas (zod, valibot, arktype, TypeBox) your app uses. @webmcp-stack/codegen turns them into WebMCP tools, written as real TypeScript files in your repo:

npx @webmcp-stack/codegen generate

In that one run, three things happen. Tools are generated: reads work immediately, mutations are generated but withheld until you enable them. Bad agent endpoints are filtered or flagged: webhooks, auth, admin. And registration is wired into your app, as two additive lines you can see and undo.

Beyond the endpoints:

• Handshake grouping. Two calls that are really one action (request an upload, then complete it) become one withheld coarse tool.
• Journeys. Multi-step goals get a shared draft, one tool per step, and a submit gate that asks the human before the real write. See Journeys.
• A skill file. generate writes .agents/skills/webmcp-tools/SKILL.md so your own coding agent knows the rules when it extends the surface. See Working with your coding agent.

Three promises

Tools work out of the box. The spec knows the method, path, and parameters, so read tools are born calling your real API with the signed-in user's session. Mutations get the same working code, commented out, one deliberate edit away.

You own the output. Generated files are plain TypeScript in your repo. No runtime dependency on webmcp-stack. Uninstall it after generating and everything still works.

Regeneration never clobbers your code. The API contract lives above a marker line and regenerates freely. Your code lives below it and is never touched. Hand-edit the generated region and you get a .new file to merge, never a silent overwrite.

What it does not do

Being clear about the edges is part of using it well:

• It does not work without a contract you maintain. It generates from an OpenAPI spec or the validation schemas your app already uses, not by scanning your code, and a vague contract makes vague tools. This is on purpose. See Who this is for.
• It does not decide your product's intents. That is your knowledge, or your agent's, guided by the skill file.
• It does not make an unsafe API safe. Every tool calls your real endpoint, so your server still validates, authorizes, and rate-limits.
• It does not run a model. Generation is deterministic, no key, no network.

Where to start

Status

WebMCP is an early-stage spec. The tools work today in Chrome behind a flag and in the origin trial, and elsewhere with a small polyfill. OpenAPI is the supported source; validation schemas are supported; tRPC is on the roadmap.