WebMCP Kit Demo

This repository is the standalone Astro + Vue demo for @vampaz/webmcp-kit. It shows how an app exposes narrow, schema-validated actions while retaining ownership of scope, guards, confirmation, execution, and UI state.

The demo separates three runtime layers that are easy to confuse:

Native browser agent: discovers tools through document.modelContext when the browser supports WebMCP.
Fallback registry: keeps the same app tools available to devtools, tests, and unsupported browsers without granting native browser-agent access.
In-page planner: drives the visible command bar and execution trace; it can use deterministic planning, browser-local AI, Chrome built-in AI, app-owned endpoints, or WebMCP-hosted planning.

The home page’s Run instant proof action temporarily uses the deterministic demo planner. It demonstrates planning, input validation, and app-owned execution without an API key, network planner call, or model download.

The adjacent stock-guard proof links to /commerce/?proof=guard and automatically runs the deterministic commerce example, showing the app reject an impossible quantity without calling the hosted planner.

Demo Routes

/: inventory selection and sorting with stable item IDs.
/invoices/: chained selection and status updates with confirmation.
/commerce/: catalog and cart actions with stock guards and checkout confirmation.
/flights/: scoped flight search and selection.
/support/: form-backed support tools and ticket state changes.
/guide/: commands, expected tool calls, and safety boundaries for every demo route.
/developers/: library integration quickstart.
/readme/: rendered repository and hosted-planner documentation from this README.

Run Locally

The project uses Node 24.12.0 from .nvmrc and npm.

nvm use
npm install
npm run dev:npm

npm run dev:npm runs against the published @vampaz/webmcp-kit package. For side-by-side library development, place the kit repository at ../web-mcp and run:

npm run dev

The background Astro server uses https://webmcp.localtest.me by default, with upstream port 60001. Use npm run start:npm or npm run start when you also want to follow the Astro development logs.

Core tools, the fallback registry, deterministic planning, and browser-local options do not require a WebMCP publishable key. Copy .env.example to .env only when you need authentication, hosted planning, provider APIs, or Cloudflare-backed development features.

Verify

npm run test
npm run typecheck
npm run lint
npm run format:check
npm run test:e2e

The app deploys as a Cloudflare Worker through the Astro Cloudflare adapter. Deployment is normally handled by GitHub and Cloudflare CI after changes reach the remote repository.

WebMCP Hosted Planner Integration

Use WebMCP hosted planning in your own website or web app with the open-source @vampaz/webmcp-kit package and a WebMCP publishable key.

This guide is for paying WebMCP customers who want natural-language commands in their product without putting OpenAI, OpenRouter, or other provider secrets in the browser. Your app keeps ownership of tools, permissions, confirmations, and state changes. WebMCP hosts the planner call behind your project policy.

Use this repository as a reference implementation; copy the integration pattern into your own app with your own WebMCP project key.

What You Need

A WebMCP account with access to hosted planning.
A project in the WebMCP dashboard.
A publishable key for the browser origins that will use hosted planning.
A web app that can install npm packages and run browser-side TypeScript or JavaScript.

Create A Publishable Key

Sign in at https://webmcp.conekto.eu/login.
Open the dashboard and choose the project that should own the key.
Click Configure keys.
In New key, choose a name and environment.
Select Hosted OpenAI planner as the service.
Add the browser origins that are allowed to call hosted planning, one per line:

https://your-app.example
http://localhost:5173

Click Create key.
Copy the raw key from Copy this key now. It is shown once.

The key is publishable, so it can be included in browser configuration. It is still scoped to your project, service, environment, allowed origins, model policy, quota, and revocation state.

Install The Kit

npm install @vampaz/webmcp-kit

Use whatever public environment variable prefix your app framework expects. For example, Vite apps expose browser variables with VITE_...; Astro apps can use PUBLIC_....

VITE_WEBMCP_PUBLISHABLE_KEY=wmcp_pk_live_...

Register Your App Tools

Register narrow, typed actions that your app already knows how to perform. Tool execution happens in your app, so your existing authorization, validation, and UI state remain in charge.

import { defineTool, registerTool } from '@vampaz/webmcp-kit'

interface SearchProductsInput {
  query: string
}

registerTool(
  defineTool<SearchProductsInput>({
    name: 'search_products',
    description: 'Search visible products by query.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Product name, category, or keyword to search for.'
        }
      },
      required: ['query'],
      additionalProperties: false
    },
    annotations: {
      readOnlyHint: true
    },
    execute(input) {
      return searchProducts(input.query)
    }
  })
)

Use confirmations or your own approval UI for tools that create orders, update records, send messages, charge cards, or otherwise change important state.

Connect Hosted Planning

import {
  createHostedOpenAIPlanner,
  defineWebMCPCommandInput,
  type WebMCPCommandInputElement
} from '@vampaz/webmcp-kit'

defineWebMCPCommandInput()

const webmcpAccessKey = import.meta.env.VITE_WEBMCP_PUBLISHABLE_KEY
const commandInput = document.querySelector<WebMCPCommandInputElement>('webmcp-command-input')

commandInput?.configure({
  context() {
    return {
      page: 'products',
      visibleProducts: getVisibleProducts()
    }
  },
  initialPlannerOptionId: 'webmcp-hosted-openai',
  plannerOptions: [
    {
      id: 'webmcp-hosted-openai',
      label: 'WebMCP hosted OpenAI',
      modelOptions: [
        {
          label: 'GPT-5.6 Luna',
          model: 'gpt-5.6-luna'
        }
      ],
      createPlanner(options) {
        return createHostedOpenAIPlanner({
          accessKey: webmcpAccessKey,
          endpoint: 'https://webmcp.conekto.eu/api/webmcp/plan',
          model: options?.model ?? 'gpt-5.6-luna',
          sessionEndpoint: 'https://webmcp.conekto.eu/api/webmcp/session'
        })
      }
    }
  ]
})

Place the command input wherever users should enter natural-language commands:

<webmcp-command-input></webmcp-command-input>

How Hosted Planning Works

The browser sends the publishable key to the hosted session endpoint:

POST https://webmcp.conekto.eu/api/webmcp/session

WebMCP validates the key against your project policy. If validation succeeds, the session endpoint returns a short-lived wmcp_session... token. The kit then calls the planner endpoint with that session token:

POST https://webmcp.conekto.eu/api/webmcp/plan
Authorization: Bearer wmcp_session...

Do not send the publishable key as the Authorization header to the planner endpoint. Do not put provider secrets in your browser app.

Rotate Or Revoke A Key

To rotate a key, create or rotate to a new publishable key, release the new browser configuration, then revoke the old key from the key table.

Revoked, expired, wrong-origin, wrong-service, and quota-exhausted keys stop minting new sessions immediately.

Troubleshooting

Origin is not allowed for this WebMCP access key.: add the exact browser origin that is calling the hosted service.
WebMCP publishable license is required for this paid service.: the app did not pass the publishable key to createHostedOpenAIPlanner().
WebMCP session token is required for this paid service.: the app called the planner endpoint directly instead of letting the kit mint a session first.
Model is not allowed for this paid service.: choose a model enabled for the project key.
WebMCP access key was revoked, expired, or quota is exhausted: create or rotate to an active key.