webmcp-sdk

AI Disclosure: This README was written with AI assistance and reviewed for accuracy.

The developer toolkit for W3C WebMCP -- the standard shipping in Chrome 146

Make any website agent-ready in 10 minutes. Built for navigator.modelContext.

✅ Google + W3C Validated — Why Now Is the Moment

March 2026 update: Google shipped WebMCP in Chrome 146 Canary. Google, Microsoft, and W3C co-authored the specification. This is not a startup experiment — it's Big Tech stamping a new web standard.

Why Now?

• Chrome 146 Canary shipped WebMCP in February 2026. Broad stable release expected mid-to-late 2026.
• Google + Microsoft + W3C co-authored the spec. Three institutions that don't move together unless something matters.
• Real implementations are live. LocalPlate (restaurant booking) shipped WebMCP on Astro. Existing HTML form sites become agent-compatible with minimal changes.
• The adoption curve is early. Developers who ship WebMCP integrations now own the search results, the tutorials, and the mindshare when the stable release lands.
• webmcp-sdk is the only TypeScript-first implementation toolkit. We built it before the spec finalized and we maintain it as the standard evolves.

If you're building for the agentic web, the window to establish yourself as an early implementer is right now.

Why webmcp-sdk?

Google and Microsoft co-authored the W3C WebMCP specification. The standard shipped in Chrome 146 Canary (February 2026). We built the implementation toolkit.

The raw navigator.modelContext API is low-level. webmcp-sdk gives developers a TypeScript-first, production-ready layer on top of it:

• Zero to agent-ready in 10 minutes -- declarative HTML attributes or imperative JavaScript
• Security middleware built in -- rate limiting, input sanitization, audit logging
• React hooks -- useWebMCPTool() registers on mount, cleans up on unmount
• Testing utilities -- mock browser context, test runner, quality scorer
• agentwallet-sdk compatible -- plug in x402 agent payments with 2 lines of code
• 50/50 compatibility tests passing on Chrome 146 Canary

If you are building for the agentic web, this is the toolkit.

Quick Install

npm i webmcp-sdk

Fastest Path to First Verified Success

import { createKit, defineTool } from 'webmcp-sdk';

const kit = createKit({ prefix: 'demo' });

kit.register(defineTool(
  'hello',
  'Return a greeting for the supplied name.',
  {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Name to greet' }
    },
    required: ['name']
  },
  async ({ name }) => {
    return { message: `Hello, ${name}!` };
  }
));

const result = await kit.invoke('demo.hello', { name: 'Bill' });
console.log(result);
// { message: 'Hello, Bill!' }

This works in Node or tests with no browser setup.

When navigator.modelContext is available in the browser, kit.register(...) also registers the tool there automatically. There is no separate init() step.

Browser Registration

Canonical docs and example in this repo:

• docs/browser-hello-quickstart.md
• examples/browser-hello/

import { createKit, defineTool } from 'webmcp-sdk';

const kit = createKit({ prefix: 'myshop' });

kit.register(defineTool(
  'search',
  'Search products by keyword. Returns matching products with prices and availability.',
  {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search term' },
      limit: { type: 'number', description: 'Max results' }
    },
    required: ['query']
  },
  async ({ query, limit = 10 }) => {
    const results = await db.products.search(query, limit);
    return { products: results, count: results.length };
  }
));

If WebMCP is available, your tool is now agent-readable.

For the full browser proof path, including build, local serve, visible result, and auto-registration checks, follow docs/browser-hello-quickstart.md and use examples/browser-hello/.

React Integration

import { useWebMCPTool } from 'webmcp-sdk/react';

function ProductSearch() {
  useWebMCPTool({
    name: 'search_products',
    description: 'Search the product catalog',
    inputSchema: {
      type: 'object',
      properties: { query: { type: 'string' } },
      required: ['query']
    },
    handler: async ({ query }) => searchProducts(query)
  });

  return <SearchUI />;
}

Security Middleware (Express)

import { webmcpDiscovery } from 'webmcp-sdk/middleware/express';

app.use(webmcpDiscovery({
  serverName: 'My API',
  manifestPath: '/mcp'
}));

Testing

import { defineTool } from 'webmcp-sdk';
import { createMockContext, testTool, formatTestResults } from 'webmcp-sdk/testing';

const searchTool = defineTool(
  'search_products',
  'Search the product catalog by keyword.',
  {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search keyword' }
    },
    required: ['query']
  },
  async ({ query }) => ({ results: [{ name: `Product for ${query}` }], total: 1 })
);

const { context, invoke } = createMockContext();
context.registerTool(searchTool);

const result = await invoke('search_products', { query: 'laptop' });
console.log(result);
// { results: [{ name: 'Product for laptop' }], total: 1 }

const results = await testTool(searchTool, [
  {
    name: 'basic search',
    input: { query: 'laptop' },
    expectSuccess: true,
    validate: (value) => Array.isArray(value.results)
  }
]);

console.log(formatTestResults(results));

agentwallet-sdk Integration (x402 Payments)

Pair with agent-wallet-sdk to accept x402 micropayments inside your WebMCP tools:

import { createKit, defineTool } from 'webmcp-sdk';
import { AgentWallet } from 'agent-wallet-sdk';

const kit = createKit({ prefix: 'api' });
const wallet = new AgentWallet({ chain: 'base', privateKey: process.env.AGENT_KEY });

kit.register(defineTool(
  'premium_data',
  'Fetch premium market data (0.01 USDC per call)',
  {
    type: 'object',
    properties: {
      symbol: { type: 'string', description: 'Market symbol to fetch' },
      agentAddress: { type: 'string', description: 'Payer address to charge' }
    },
    required: ['symbol', 'agentAddress']
  },
  async ({ symbol, agentAddress }) => {
    await wallet.receiveX402Payment(agentAddress, '0.01');
    return fetchPremiumData(symbol);
  }
));

The W3C WebMCP Specification

WebMCP is a W3C draft specification that adds a navigator.modelContext API to browsers. It lets AI agents interact with web pages through a standardized interface — registering tools, reading structured context, and calling functions declared by the page.

Key links:

• W3C Spec Draft
• Chrome Status
• awesome-webmcp

Claude Code Compatibility

Companion note in this repo:

• docs/claude-code-polyfill-bridge.md

webmcp-sdk works with Claude Code's Chrome Extension through the @mcp-b/global polyfill. Here's how the pieces connect:

How it works: When Claude Code's Chrome Extension visits a page that has webmcp-sdk tool registration code on it, the extension detects navigator.modelContext (provided by the polyfill in pre-stable Chrome, or natively in Chrome 146+). Claude discovers your registered tools and can invoke them directly from the chat interface.

Setup for site owners:

You can also start from the repo example in examples/browser-hello/ and swap its demo.hello tool for your real tool.

<!-- Load the polyfill for browsers without native navigator.modelContext -->
<script src="https://unpkg.com/@mcp-b/global"></script>

<!-- Your webmcp-sdk tool registration -->
<script type="module">
  import { createKit, defineTool } from 'webmcp-sdk';

  const kit = createKit({ prefix: 'mysite' });
  kit.register(defineTool(
    'search',
    'Search this site',
    { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
    async ({ q }) => siteSearch(q)
  ));
</script>

What Claude Code users get: When visiting your page with the Claude Chrome Extension active, your site's tools appear alongside Claude's built-in MCP tools. No configuration needed on the user's side - discovery is automatic through navigator.modelContext.

Tracking native support: GitHub Issue #30645 on anthropics/claude-code tracks native WebMCP support in the Claude Chrome Extension. The polyfill bridges the gap until that ships.

Compatibility matrix:

Proxy Relay — Reach Private Endpoints From the Browser Sandbox

Chrome's Content Security Policy blocks tool handlers from calling private APIs directly. The Proxy Relay routes those calls through a local HTTP server (or a Service Worker) so your tools can reach authenticated, internal, or CORS-restricted endpoints without opening up your CSP.

Quick Start