webmcp-kit

Type-safe WebMCP tools with Zod.

What is WebMCP?

WebMCP is a browser API that lets websites expose tools to AI agent, developed under the WebML working group.

The API adds navigator.modelContext, which websites use to register tools that agents can discover and call. Think of it like making your site's functionality available to AI assistants.

Major browsers are starting to experiment with implementations.

• Chrome:
  • WebMCP is available for early preview
  • WebMCP early preview
  • TLDR: Download Chrome Canary (146+), go to about:flags and set WebMCP for testing to enabled

What does webmcp-kit do?

webmcp-kit wraps the raw WebMCP API to make building tools easier:

• Zod schemas: Define inputs once, get JSON Schema conversion and TypeScript inference
• Built-in validation: Inputs are validated against your schema before execute runs
• Less boilerplate: Feature detection, response formatting, and registration handled for you
• Automatic feature detection: Works when the API exists, falls back gracefully when it doesn't
• Dev panel: Test and debug tools in the browser without needing a real agent

import { defineTool } from 'webmcp-kit';
import { z } from 'zod';

const addToCart = defineTool({
  name: 'addToCart',
  description: 'Add a product to cart',
  inputSchema: z.object({
    productId: z.string(),
    quantity: z.number().min(1),
  }),
  execute: async ({ productId, quantity }) => {
    // productId and quantity are typed
    return `Added ${quantity}x ${productId}`;
  },
});

addToCart.register();

Install

npm install webmcp-kit zod

Requires Zod v4.

Install and Use the add-webmcp-tools Skill

Install the skill from this repository using Vercel's Skills CLI:

npx skills add victorhuangwq/webmcp-kit

Then invoke it with requests like:

• "add a webmcp tool for search"
• "debug why my tool is not in dev panel"
• "update tool schema and validation"

References:

• Skill definition: skills/add-webmcp-tools/SKILL.md
• Working demos:
  • examples/pizza-shop/README.md
  • examples/flight-booking/README.md

Usage

Define a Tool

import { defineTool } from 'webmcp-kit';
import { z } from 'zod';

const searchProducts = defineTool({
  name: 'searchProducts',
  description: 'Search the product catalog',
  inputSchema: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10),
  }),
  execute: async ({ query, limit }) => {
    const results = await db.products.search(query, limit);
    return JSON.stringify(results);
  },
});

searchProducts.register();

The schema is converted to JSON Schema for the WebMCP API. Your execute function receives typed inputs.

User Interaction

Tools can request confirmation or input from the user:

const checkout = defineTool({
  name: 'checkout',
  description: 'Complete purchase',
  inputSchema: z.object({ cartId: z.string() }),
  execute: async ({ cartId }, agent) => {
    const { confirmed } = await agent.requestUserInteraction({
      prompt: 'Confirm purchase?',
      type: 'confirmation',
    });

    if (!confirmed) return 'Cancelled';

    await processOrder(cartId);
    return 'Order placed';
  },
});

Response Helpers

import { textContent, jsonContent, errorContent } from 'webmcp-kit';

// String responses are auto-wrapped, but you can be explicit:
return textContent('Done');
return jsonContent({ status: 'ok' });
return errorContent('Something went wrong');

Dev Panel

Test tools without a real agent:

import { enableDevMode } from 'webmcp-kit/devtools';

enableDevMode();

This injects a panel that lists your tools, generates input forms from schemas, and lets you execute them.

API

defineTool(options)

const tool = defineTool({
  name: string,
  description: string,
  inputSchema: ZodSchema,
  execute: (input, agent) => Promise<string | ToolResponse>,
  annotations?: ToolAnnotations,
});

tool.register();   // Add to navigator.modelContext
tool.unregister(); // Remove from navigator.modelContext
tool.execute(input); // Call directly (for testing)

enableDevMode()

import { enableDevMode } from 'webmcp-kit/devtools';

enableDevMode();

How It Works

defineTool() creates a tool object. When you call .register():

1. It checks if navigator.modelContext exists
2. If yes, registers with the native API
3. If no, registers with an internal mock (so the dev panel still works)

Your code doesn't change based on environment. When browsers ship WebMCP support, the same code will use the real API.

Examples

• examples/pizza-shop: pizza ordering flow with multiple tools (getMenu, addToCart, checkout).
• examples/flight-booking: multi-step flight purchase flow (searchFlights, selectFlight, addTraveler, addExtras, purchaseFlight).

Both examples include setup instructions for testing with native WebMCP and mock mode.

Support

If you find webmcp-kit useful:

• Star the repo: It helps others discover the project
• Report issues: Found a bug or have a feature request? Open an issue

License

MIT