WebMCP API &
SDK Reference

1npm install @webmcp/sdk
2
3import { WebMCP } from '@webmcp/sdk';
4
5const ar = new WebMCP({
6  apiKey: process.env.WEBMCP_API_KEY  // Free tier — get yours at web-mcp.net/keys
7});

1// Scans the URL for WebMCP tools — both imperative (registerTool) and
2// declarative (HTML toolname attributes) — plus forms that SHOULD be tools
3const scan = await ar.scan('https://your-site.com');
4
5console.log(scan.score);              // 82 — Agent Readiness Score (0-100)
6console.log(scan.tools.detected);     // 8 WebMCP tools found
7console.log(scan.tools.suggested);    // 3 forms that should become tools
8console.log(scan.security.status);    // "PASSED" — no injection vulnerabilities
9console.log(scan.lint.warnings);      // 2 — description quality issues

1// Get the exact tool definitions that AI agents receive via navigator.modelContext
2const tools = await ar.tools.list({ scanId: scan.id });
3
4for (const tool of tools) {
5  console.log(`${tool.name}: ${tool.description}`);
6  console.log(`  Parameters: ${Object.keys(tool.inputSchema.properties).join(', ')}`);
7  console.log(`  Type: ${tool.registrationType}`);  // "imperative" or "declarative"
8  console.log(`  Annotations: readOnly=${tool.annotations?.readOnlyHint}`);
9}

1// Run 100 natural language prompts against your tools across 3 models
2const coverage = await ar.test.promptCoverage({
3  tools: tools,
4  promptCount: 100,
5  models: ['gemini-2.0', 'gpt-4o', 'claude-3.5'],
6  categories: ['formal', 'casual', 'multilingual', 'ambiguous']
7});
8
9console.log(coverage.overallAccuracy);    // 0.91 — 91% of prompts routed correctly
10console.log(coverage.byModel.gemini);     // 0.94 — Gemini is best for your tools
11console.log(coverage.byModel.gpt4o);      // 0.89
12console.log(coverage.byModel.claude);     // 0.90
13console.log(coverage.failures[0]);
14// { prompt: "cheap flights NYC", expected: "search_flights",
15//   got: "search_hotels", suggestion: "Add 'flights' to description" }