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 Agent-Ready

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', default: 10 }
    },
    required: ['query']
  },
  async ({ query, limit = 10 }) => {
    const results = await db.products.search(query, limit);
    return { products: results, count: results.length };
  }
));

await kit.init(); // registers with navigator.modelContext

That's it. Your site is now agent-readable.

React Integration

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

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

  return <SearchUI />;
}

Security Middleware (Express)

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

app.use('/api/agent', createWebMCPMiddleware({
  rateLimit: { requests: 100, windowMs: 60_000 },
  sanitize: true,
  audit: true
}));

Testing

import { createMockBrowserContext, WebMCPTestRunner } from 'webmcp-sdk/testing';

const ctx = createMockBrowserContext();
const runner = new WebMCPTestRunner(ctx);

const score = await runner.score(myTool, [
  { input: { query: 'laptop' }, expectedOutput: { products: expect.arrayContaining([]) } }
]);

console.log(score); // { pass: 10, fail: 0, score: 1.0 }

agentwallet-sdk Integration (x402 Payments)

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

import { createKit } 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' } }, required: ['symbol'] },
  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

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 initialized, 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:

<!-- 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)
  ));
  await kit.init();
</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:

| Browser | WebMCP Support | Notes | |---|---|---| | Chrome 146 Canary | Native navigator.modelContext | Full support, no polyfill needed | | Chrome stable (pre-146) | Via @mcp-b/global polyfill | Works with Claude Chrome Extension | | Edge | Expected (Chromium-based) | Tracking W3C spec adoption | | Firefox / Safari | Not yet | W3C working group stage |

Contributing

PRs welcome. Run npm test before submitting. The spec is evolving - if you find a Chrome 146 compatibility issue, open an issue with your Canary version.

License

MIT