---
title: How it works
description: WebMCP Kit lets you think in user journeys instead of API endpoints. Build tools that work together to create a coherent agent experience across your site.
---


## The idea

A website already knows how to do everything a visitor needs — search, book, buy, ask. The problem is that an AI agent can't reach that logic; it can only poke at the rendered page. WebMCP Kit's job is to expose a *small, deliberate* set of that logic as typed tools.

Two principles drive every decision it makes:

**Tools are journeys, not endpoints.** The question is "what does a visitor come here to do?", never "what routes does the API have?". A booking site gets `book_appointment`; it does not get a wrapper for every REST endpoint. Most sites end up with 3–10 tools.

**The developer approves before anything is written.** The plan you review — tool names, exact descriptions, what each is wired to — is the contract. No file, branch, or dependency exists until you say yes.

## The six phases

| Phase | What happens |
| --- | --- |
| **A — Understand** | Reads manifests, routes, forms, and the data layer. Maps what a visitor can see and do. Read-only. |
| **B — Select** | Matches the site to a journey category and picks the tools worth having. No match → it says so instead of forcing a weak fit. |
| **C — Wire** | For each tool, picks the safest concrete path: the app's own client data layer first, then same-origin routes, then client actions. Anything uncertain becomes a question for you, with a stated default. |
| **D — Review** | The plan is presented to you. Hard gate: explicit approval or nothing proceeds. |
| **E — Generate** | Writes the tools against the [`@nekuda/webmcp-sdk`](https://www.npmjs.com/package/@nekuda/webmcp-sdk), in your repo's own language and conventions. |
| **F — Verify** | Type checks → site boots → each tool registers where declared → tools actually work when called. Failures are fixed or dropped, never shipped. |

The output is a PR on a `webmcp/tools-v0` branch. Its body is the approved plan plus a per-tool verification table, so the review artifact and the code always travel together.

## What it never does

These are hard rules, not defaults you have to configure:

- **Your code stays local.** No customer code, routes, or schemas are sent to any external service. The analysis runs entirely in your agent session.
- **No fake data.** A journey with no safe wiring path is flagged *needs developer wiring* — never stubbed with invented responses.
- **Dangerous actions keep a boundary.** A payment, cancellation, or delete never completes in a single agent call. Generated tools stop at a reversible point — a pending order, a prepared cancellation — and hand the final step to your site's own confirmation flow.
- **Your server stays the authority.** It only wraps mutations whose routes enforce authentication and authorization server-side. An endpoint that trusts a hidden client button gets flagged, not wrapped.
- **Nothing ships broken.** A tool that fails verification is fixed or dropped. Only *verified* and explicitly-flagged *could-not-verify* tools reach the PR.

## Re-runs don't churn

Every generated tool carries a `stableKey` — a durable identity like `cart.add` that is authored once and survives re-runs and renames. Run the skill again after a redesign and your tools keep their identity instead of being recreated as strangers.

## Sometimes the answer is a plan, not code

If most of a site's journeys can't be wired safely, the honest outcome is a reviewed plan that says exactly why — with no code. The kit treats that as a legitimate result, not a failure.

## Optional: review in a live page

If you'd rather review the plan in a browser page than in chat, the implement skill can run an **interactive loop**: same phases, same approval gate, but the plan renders in a live Explorer page and your approval is a click. The loop's state lives in a git-tracked `.webmcp/` folder in your repo.