API Reference — WebMCP REST & SDK Documentation

https://api.web-mcp.net/v1v1

Operational

API Reference

Getting Started4

Scanning & Scoring7

Tool Management8

Testing & Quality3

Security & Compliance3

Agent Simulation4

Analytics & Monitoring6

Discovery Hub2

AI Co-Pilot3

Webhooks & Events4

Reference2

_00 quick_start

Quick Start

Get your first Agent Readiness Score with a single API call. No complex setup, no configuration — just scan and see what AI agents see.

terminal

$npm install @webmcp/sdk

→✓ Installed @webmcp/sdk@1.4.2

$webmcp-cli scan https://travel-demo.bandarra.me --deep

→Score: 82/100 — 2 tools found — 3 recommendations

1curl -X POST https://api.web-mcp.net/v1/scan \
2  -H "Authorization: Bearer ar_live_sk_YOUR_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://travel-demo.bandarra.me",
6    "options": { "deep": true }
7  }'

Response200 OK

Scan completed — 2 WebMCP tools discovered with recommendations.

1{
2  "id": "scan_7xK2mP9q",
3  "status": "completed",
4  "url": "https://travel-demo.bandarra.me",
5  "score": 82,
6  "tools": [
7    {
8      "name": "searchFlights",
9      "description": "Search available flights between airports",
10      "score": 91
11    },
12    {
13      "name": "bookFlight",
14      "description": "Book a flight with passenger details",
15      "score": 78
16    }
17  ],
18  "recommendations": [
19    "Add error descriptions to bookFlight parameters",
20    "Include example values in searchFlights schema"
21  ],
22  "timing": { "total_ms": 2340, "scan_ms": 1200 }
23}

01 Fetched page → detected 2 WebMCP tools via registerTool()02 Validated inputSchema against JSON Schema standards03 Computed Agent Readiness Score: 82/100

_00

_01 introduction

Introduction

The WebMCP API gives you programmatic access to the complete Agent Readiness platform — scanning, tool management, prompt coverage testing, security analysis, agent simulation, analytics, and the Discovery Hub.

Base URL

All requests use HTTPS. HTTP requests are redirected.

1https://api.web-mcp.net/v1

API Versioning

The current version is v1. The version is included in the URL path. When breaking changes are introduced, a new version is released. Previous versions are supported for 12 months after deprecation notice.

Request & Response Format

Aspect	Detail
`Content-Type`	application/json for all request/response bodies
`Methods`	GET for reads, POST for creates, PUT for full updates, PATCH for partial, DELETE for removals
`Pagination`	Cursor-based. Response includes hasMore, nextCursor. Pass cursor param to paginate.
`Filtering`	field[operator]=value syntax (e.g., score[gte]=75)
`Timestamps`	ISO 8601 format: 2026-02-09T10:30:00Z
`IDs`	Prefixed strings: scan_, tool_, test_, alert_, wh_
`Idempotency`	POST requests accept an Idempotency-Key header
`Request IDs`	Every response includes X-Request-Id header for debugging

SDKs

Official SDKs handle auth, retries, pagination, and rate limiting automatically.

Language	Install	Docs
`JavaScript/TypeScript`	npm install @webmcp/sdk	JS SDK Docs →
`Python`	pip install webmcp	Python SDK Docs →
`Go`	go get github.com/webmcp/webmcp-go	Go SDK Docs →
`CLI`	npm install -g @webmcp/cli	CLI Reference →

_02

_02 authentication

Authentication

Every API request requires a valid API key. Keys are scoped by permission level and tied to your organization for audit logging.

Bearer Token Authentication

Include your API key in the Authorization header. All keys are prefixed for easy identification: • ar_live_sk_ → Production keys (live data, real scans) • ar_test_sk_ → Test keys (sandbox mode, no billing)

1curl -H "Authorization: Bearer ar_live_sk_1234567890" \
2  "https://api.web-mcp.net/v1/score?url=https://example.com"

Permission Scopes

Keys are scoped to limit blast radius. Choose the minimum scope needed.

Scope	Permissions	Use Case
`scan:read`	Read scan results, scores, tool lists	Dashboards, reporting
`scan:write`	Create scans, trigger analyses	CI/CD pipelines, automation
`tools:manage`	Create, update, delete tool definitions	Tool Studio integrations
`test:run`	Execute prompt coverage tests, simulations	QA workflows
`security:scan`	Run security analyses, compliance reports	Security pipelines
`analytics:read`	Read traffic, funnel, and revenue data	Analytics dashboards
`webhooks:manage`	Create, update, delete webhooks	Event-driven integrations
`admin`	All permissions + key management + billing	Full platform access

Multi-Site Management

Partners managing multiple client sites use a single API key with site-scoped operations. Pass the X-Site-Id header to specify which site context to use.

1curl -H "Authorization: Bearer ar_live_sk_partner_xxx" \
2  -H "X-Site-Id: site_client1" \
3  https://api.web-mcp.net/v1/score

_03

_03 errors

Errors

WebMCP uses conventional HTTP status codes and returns structured error responses with domain-specific codes that explain exactly what went wrong and how to fix it.

HTTP Status Codes

Code	Meaning	When You’ll See It
`200`	Success	Successful GET, PUT, PATCH, DELETE
`201`	Created	Successful POST that creates a resource
`202`	Accepted	Async operation started (deep scans, prompt tests)
`400`	Bad Request	Invalid parameters, malformed JSON
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid key but insufficient scope
`404`	Not Found	Resource doesn’t exist
`429`	Rate Limited	Too many requests — check rate limit headers
`500`	Server Error	Something went wrong on our end

Error Response Format

Every error returns a consistent JSON structure with a machine-readable code, human-readable message, contextual details, and a link to documentation:

1{
2  300">"error": {
3    300">"code": 300">"TOOL_SCHEMA_INVALID",
4    300">"message": 300">"The inputSchema 400300">">for tool 300">'search-flights' contains validation errors",
5    300">"details": {
6      300">"tool": 300">"search-flights",
7      300">"violations": [
8        { 300">"path": 300">"properties.origin", 300">"issue": 300">"Missing 300">'description'" },
9        { 300">"path": 300">"properties.passengers", 300">"issue": 300">"Type should be 300">'integer'" }
10      ],
11      300">"docsUrl": 300">"https:25 italic300">">//web-mcp.net/docs/schema-validation"
12    },
13    300">"requestId": 300">"req_8xK2mP9qR3"
14  }
15}

Error Codes — General

Code	HTTP	Description
`INVALID_JSON`	400	Request body is not valid JSON
`MISSING_REQUIRED_FIELD`	400	A required field is missing from the request
`INVALID_FIELD_VALUE`	400	A field value doesn't match the expected type or format
`AUTHENTICATION_REQUIRED`	401	No API key provided
`INVALID_API_KEY`	401	API key is malformed or revoked
`INSUFFICIENT_SCOPE`	403	API key lacks the required permission scope
`RESOURCE_NOT_FOUND`	404	The requested resource does not exist
`RATE_LIMIT_EXCEEDED`	429	Too many requests — back off and retry
`INTERNAL_ERROR`	500	Something went wrong on our side — retry with exponential backoff

Error Codes — Scanning

Code	HTTP	Description
`URL_NOT_REACHABLE`	422	The target URL returned a non-2xx status or timed out
`URL_BLOCKED_ROBOTS`	422	The URL is blocked by robots.txt
`SCAN_TIMEOUT`	408	Page didn't load within the configured timeout
`NO_TOOLS_DETECTED`	200	Scan succeeded but no WebMCP tools were found
`BATCH_SIZE_EXCEEDED`	400	Batch scan exceeds max 50 URLs per request
`DEEP_SCAN_QUOTA_EXCEEDED`	429	Daily deep scan limit reached for your plan

Error Codes — Tool / Schema

Code	HTTP	Description
`TOOL_SCHEMA_INVALID`	400	JSON Schema validation failed — see details.violations
`TOOL_NAME_CONFLICT`	409	A tool with this name already exists for this site
`TOOL_DESCRIPTION_TOO_SHORT`	400	Description must be at least 20 characters
`IMPORT_SOURCE_UNREACHABLE`	422	Could not fetch the spec from sourceUrl
`IMPORT_FORMAT_UNSUPPORTED`	400	Source format not recognized

Error Codes — Testing

Code	HTTP	Description
`TEST_BUDGET_EXCEEDED`	402	LLM test budget exhausted for this billing period
`MODEL_UNAVAILABLE`	503	One or more requested models are temporarily unavailable
`PROMPT_COUNT_INVALID`	400	promptCount must be between 10 and 200

Troubleshooting Common Issues

Symptom	Cause	Fix
`401 on every request`	API key not in header or malformed	Use Authorization: Bearer ar_live_sk_...
`403 with valid key`	Key scope too narrow	Create a new key with the required scope in Settings → API Keys
`Scan returns 0 tools`	Tools registered after DOMContentLoaded	Set options.waitFor to a CSS selector that appears after tool registration
`Deep scan times out`	Page takes too long to fully render	Increase options.timeout to 60–120s, or simplify page load
`Prompt coverage is low`	Tool descriptions are too vague	Use the A/B test endpoint to compare description variants
`Webhook not receiving events`	Endpoint not returning 2xx	Ensure your webhook URL returns 200 within 5s — we retry 3× with exponential backoff
`Rate limited unexpectedly`	Burst limit exceeded	Space requests ≥100ms apart or use the SDK's built-in rate limiter

_04

_04 scanning

Scanning & Scoring

Scan any URL to detect WebMCP tools (registered via navigator.modelContext.registerTool() or declared via HTML form attributes), calculate the Agent Readiness Score, and get actionable recommendations.

Create Scan

POST/v1/scan⏱~2s quick / ~45s deep

Scan a URL for WebMCP tool declarations and calculate its Agent Readiness Score. Quick scans run static analysis; deep scans add LLM-powered prompt coverage testing across multiple models.

Parameters

Name	Type	Status	Description
`url`	`string`	Required	The URL to scan. Must be publicly accessible via HTTPS.
`options.deep`	`boolean`	false	Quick scan (false) or deep scan with LLM testing (true).
`options.timeout`	`number`	30	Page load timeout in seconds. Increase for SPAs. Max 120.
`options.waitFor`	`string`	Optional	CSS selector to wait for before scanning. Essential for SPAs.
`options.models`	`string[]`	["gemini-2.0-flash"]	LLM models for prompt coverage testing (deep scan only).
`options.promptCount`	`number`	25	Auto-generated test prompts per tool. Range: 10–200.
`options.industry`	`string`	auto	Industry vertical for benchmark comparison.
`options.callbackUrl`	`string`	Optional	URL to POST results to when scan completes.

1curl -X POST https://api.web-mcp.net/v1/scan \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://travel-demo.bandarra.me",
6    "options": {
7      "deep": true,
8      "models": ["gemini-2.0-flash", "gpt-4o", "claude-sonnet-4"],
9      "promptCount": 50,
10      "industry": "travel"
11    }
12  }'

Response200 OK

1{
2  "id": "scan_7xK2mP9q",
3  "status": "completed",
4  "url": "https://travel-demo.bandarra.me",
5  "score": 82,
6  "grade": "A-",
7  "components": {
8    "implementation": { "score": 91, "label": "Excellent" },
9    "promptCoverage": { "score": 87, "label": "Good" },
10    "security": { "score": 76, "label": "Needs Work" },
11    "reliability": { "score": 79, "label": "Good" },
12    "bestPractices": { "score": 85, "label": "Good" }
13  },
14  "tools": [
15    { "name": "searchFlights", "type": "imperative", "quality": "high" },
16    { "name": "selectFlight", "type": "imperative", "quality": "high" },
17    { "name": "bookFlight", "type": "imperative", "quality": "medium" }
18  ],
19  "recommendations": [
20    {

Get Scan

GET/v1/scan/{scanId}⚡~100ms

Retrieve results of a completed scan. For deep scans (async), poll this endpoint until status changes from "processing" to "completed".

Parameters

Name	Type	Status	Description
`scanId`	`string`	Required	Scan ID (e.g., scan_7xK2mP9q)
`include`	`string`	Optional	Comma-separated: tools, recommendations, benchmarks, promptCoverage, security. Default: all.

1curl "https://api.web-mcp.net/v1/scan/scan_7xK2mP9q" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

List Scans

GET/v1/scans⚡~150ms

List all scans for your organization with filtering and sorting.

Parameters

Name	Type	Status	Description
`cursor`	`string`	Optional	Pagination cursor from previous response
`limit`	`number`	20	Results per page (max 100)
`url`	`string`	Optional	Filter by exact URL
`score[gte]`	`number`	Optional	Only scans with score >= value
`tier`	`string`	Optional	Filter by scan tier: "quick" or "deep"
`sort`	`string`	-createdAt	Sort field. Prefix with - for descending.

1curl "https://api.web-mcp.net/v1/scans?score[gte]=75&limit=10" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "data": [
3    { "id": "scan_7xK2mP9q", "url": "https://travel-demo.bandarra.me", "score": 82, "grade": "A-", "status": "completed" },
4    { "id": "scan_3mN8pK2x", "url": "https://restaurant-example.com", "score": 45, "grade": "D+", "status": "completed" }
5  ],
6  "hasMore": true,
7  "nextCursor": "scan_3mN8pK2x",
8  "total": 47
9}

Batch Scan

POST/v1/scans/batch🔄varies

Scan multiple URLs in a single request. Results are delivered asynchronously via callbackUrl or polling. Essential for agencies managing multiple client sites.

Parameters

Name	Type	Status	Description
`urls`	`string[]`	Required	Array of URLs to scan (max 50 per batch)
`options`	`object`	Optional	Same options as single scan, applied to all URLs
`options.callbackUrl`	`string`	Optional	URL to POST batch results when all scans complete

1curl -X POST https://api.web-mcp.net/v1/scans/batch \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "urls": [
6      "https://client1-hotel.com",
7      "https://client2-restaurant.com",
8      "https://client3-ecommerce.com"
9    ],
10    "options": { "deep": false }
11  }'

Response200 OK

1{
2  "batchId": "batch_9xR3mK7p",
3  "status": "processing",
4  "total": 3,
5  "completed": 0,
6  "scans": [
7    { "id": "scan_a1b2c3", "url": "https://client1-hotel.com", "status": "queued" },
8    { "id": "scan_d4e5f6", "url": "https://client2-restaurant.com", "status": "queued" },
9    { "id": "scan_g7h8i9", "url": "https://client3-ecommerce.com", "status": "queued" }
10  ]
11}

CI/CD Gate

POST/v1/scan/gate⏱~3s quick / ~60s deep

Purpose-built for CI/CD pipelines. Scans a URL and returns a pass/fail verdict based on configurable thresholds. Returns exit-code-friendly response.

Parameters

Name	Type	Status	Description
`url`	`string`	Required	URL to scan (usually your staging/preview environment)
`thresholds.minScore`	`number`	Optional	Minimum Agent Readiness Score to pass (0–100)
`thresholds.maxSecurityFindings`	`number`	Optional	Max high-severity security findings (0 = zero tolerance)
`thresholds.minPromptCoverage`	`number`	Optional	Minimum prompt coverage ratio (0.0–1.0)
`thresholds.requiredTools`	`string[]`	Optional	Tool names that MUST be detected
`comparison.baselineScanId`	`string`	Optional	Compare against a previous scan for regression detection

1curl -X POST https://api.web-mcp.net/v1/scan/gate \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://staging.your-app.com",
6    "thresholds": {
7      "minScore": 75,
8      "maxSecurityFindings": 0,
9      "minPromptCoverage": 0.80
10    }
11  }'

Response200 OK

1{
2  "verdict": "fail",
3  "scan": { "id": "scan_cIpL3x9q", "score": 71, "grade": "B-" },
4  "gates": [
5    { "gate": "minScore", "threshold": 75, "actual": 71, "passed": false },
6    { "gate": "maxSecurityFindings", "threshold": 0, "actual": 1, "passed": false },
7    { "gate": "minPromptCoverage", "threshold": 0.80, "actual": 0.87, "passed": true }
8  ],
9  "summary": "Deployment blocked: score 71 < threshold 75",
10  "exitCode": 1
11}

Get Score

GET/v1/score⚡~100ms

Get the latest Agent Readiness Score for a URL without triggering a new scan.

Parameters

Name	Type	Status	Description
`url`	`string`	Required	Site URL
`include`	`string`	Optional	Comma-separated: components, benchmarks, recommendations, badge

1curl "https://api.web-mcp.net/v1/score?url=https://travel-demo.bandarra.me&include=components,benchmarks" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "url": "https://travel-demo.bandarra.me",
3  "score": 82,
4  "grade": "A-",
5  "components": {
6    "implementation": 91,
7    "promptCoverage": 87,
8    "security": 76,
9    "reliability": 79,
10    "bestPractices": 85
11  },
12  "benchmarks": {
13    "industry": "travel",
14    "percentile": 78,
15    "industryAverage": 52
16  },
17  "lastScannedAt": "2026-02-09T10: 30: 00Z"
18}

Score History

GET/v1/score/history⚡~150ms

Track score changes over time. Essential for dashboards and demonstrating improvement progress.

Parameters

Name	Type	Status	Description
`url`	`string`	Required	Site URL
`startDate`	`string`	30 days ago	ISO 8601 start date
`endDate`	`string`	now	ISO 8601 end date
`granularity`	`string`	day	Aggregation: day, week, month

1curl "https://api.web-mcp.net/v1/score/history?url=https://travel-demo.bandarra.me&granularity=day" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "url": "https://travel-demo.bandarra.me",
3  "data": [
4    { "date": "2026-02-01", "score": 45, "grade": "D+" },
5    { "date": "2026-02-03", "score": 62, "grade": "C+", "delta": "+17" },
6    { "date": "2026-02-05", "score": 74, "grade": "B", "delta": "+12" },
7    { "date": "2026-02-09", "score": 82, "grade": "A-", "delta": "+8" }
8  ],
9  "summary": {
10    "startScore": 45,
11    "endScore": 82,
12    "totalImprovement": "+37"
13  }
14}

_05

_05 tools

Tool Management

Create, validate, lint, version, and export WebMCP tool definitions. These endpoints power the Tool Studio — the authoring environment where developers define how AI agents interact with their websites.

List Tools

GET/v1/tools⚡~100ms

List all tool definitions for your organization, optionally filtered by site.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Optional	Filter by site URL
`quality`	`string`	Optional	Filter by quality: high, medium, low
`limit`	`number`	20	Results per page (max 100)

1curl "https://api.web-mcp.net/v1/tools?siteUrl=https://travel-demo.bandarra.me" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "data": [
3    {
4      "id": "tool_Kx9mR3pQ",
5      "name": "searchFlights",
6      "description": "Search for available flights between airports",
7      "quality": "high",
8      "lintIssues": 0,
9      "version": 3
10    }
11  ],
12  "hasMore": false,
13  "total": 3
14}

Create Tool

POST/v1/tools⚡~200ms

Create a new tool definition. Immediately validated against JSON Schema draft-07 and linted against WebMCP best practices.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	The website this tool belongs to
`name`	`string`	Required	Tool name. Must be unique per site.
`description`	`string`	Required	What this tool does. Min 20 chars.
`inputSchema`	`object`	Required	JSON Schema draft-07 describing input parameters.
`annotations`	`object`	Optional	MCP annotations: readOnlyHint, destructiveHint, idempotentHint

1curl -X POST https://api.web-mcp.net/v1/tools \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "siteUrl": "https://travel-demo.bandarra.me",
6    "name": "searchFlights",
7    "description": "Search for available flights between airports by date and passenger count",
8    "inputSchema": {
9      "type": "object",
10      "properties": {
11        "origin": { "type": "string", "description": "Departure airport IATA code" },
12        "destination": { "type": "string", "description": "Arrival airport IATA code" },
13        "departureDate": { "type": "string", "format": "date" }
14      },
15      "required": ["origin", "destination", "departureDate"]
16    },
17    "annotations": { "readOnlyHint": true }
18  }'

Response200 OK

1{
2  "id": "tool_Kx9mR3pQ",
3  "name": "searchFlights",
4  "lint": {
5    "score": 88,
6    "issues": [
7      { "severity": "info", "rule": "enum-descriptions", "detail": "Consider adding titles to enum values" }
8    ]
9  },
10  "generatedTests": { "count": 12 }
11}

Get Tool

GET/v1/tools/{toolId}⚡~100ms

Retrieve a single tool definition with optional includes for lint results, version history, generated code, and prompt coverage data.

Parameters

Name	Type	Status	Description
`toolId`	`string`	Required	Tool ID (e.g., tool_Kx9mR3pQ)
`include`	`string`	Optional	Comma-separated: lint, versions, code, promptCoverage

1curl "https://api.web-mcp.net/v1/tools/tool_Kx9mR3pQ?include=lint,versions" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "id": "tool_Kx9mR3pQ",
3  "name": "searchFlights",
4  "description": "Search for available flights between airports by date and passenger count",
5  "inputSchema": {
6    "type": "object",
7    "properties": {
8      "origin": { "type": "string", "description": "Departure airport IATA code" },
9      "destination": { "type": "string", "description": "Arrival airport IATA code" },
10      "departureDate": { "type": "string", "format": "date" }
11    },
12    "required": ["origin", "destination", "departureDate"]
13  },
14  "annotations": { "readOnlyHint": true },
15  "quality": "high",
16  "version": 3,
17  "lint": { "score": 92, "issues": [] },
18  "versions": [
19    { "version": 3, "createdAt": "2026-02-09T10: 00: 00Z", "changelog": "Added cabin class parameter" },
20    { "version": 2, "createdAt": "2026-02-05T14: 00: 00Z", "changelog": "Improved description" },

Update Tool

PUT/v1/tools/{toolId}⚡~200ms

Update a tool definition. Creates a new version automatically. Returns an impact analysis showing how the change affects prompt coverage and security posture.

Parameters

Name	Type	Status	Description
`toolId`	`string`	Required	Tool ID
`description`	`string`	Optional	Updated description
`inputSchema`	`object`	Optional	Updated JSON Schema
`annotations`	`object`	Optional	Updated MCP annotations
`changelog`	`string`	Optional	Description of what changed (stored in version history)

1curl -X PUT https://api.web-mcp.net/v1/tools/tool_Kx9mR3pQ \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "description": "Search for available flights between airports by date, passenger count, and cabin class. Accepts IATA codes or city names.",
6    "changelog": "Expanded description with cabin class and city name support"
7  }'

Response200 OK

1{
2  "id": "tool_Kx9mR3pQ",
3  "version": 4,
4  "lint": { "score": 95, "issues": [] },
5  "impact": {
6    "promptCoverage": { "before": 0.82, "estimated": 0.91, "change": "+11%" },
7    "securityScore": { "before": 76, "estimated": 76, "change": "0" }
8  }
9}

Delete Tool

DELETE/v1/tools/{toolId}⚡~100ms

Soft-delete a tool definition. The tool is marked as deleted and excluded from scans, but can be restored within 30 days.

Parameters

Name	Type	Status	Description
`toolId`	`string`	Required	Tool ID to delete
`force`	`boolean`	false	Permanently delete without 30-day restore window

1curl -X DELETE "https://api.web-mcp.net/v1/tools/tool_Kx9mR3pQ" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "id": "tool_Kx9mR3pQ",
3  "deleted": true,
4  "restorable": true,
5  "restoreDeadline": "2026-03-11T10: 30: 00Z"
6}

Lint Tool

POST/v1/tools/lint⚡~100ms • Free

Validate and lint a tool definition without creating it. FREE on all plans — no authentication required. Powers the CLI command: npx webmcp-cli lint tool.json

Parameters

Name	Type	Status	Description
`name`	`string`	Required	Tool name
`description`	`string`	Required	Tool description
`inputSchema`	`object`	Required	JSON Schema for parameters

1curl -X POST https://api.web-mcp.net/v1/tools/lint \
2  -H "Content-Type: application/json" \
3  -d '{
4    "name": "searchFlights",
5    "description": "Search for flights",
6    "inputSchema": { "type": "object", "properties": {} }
7  }'

Response200 OK

1{
2  "valid": true,
3  "lint": {
4    "score": 62,
5    "issues": [
6      { "severity": "warning", "rule": "description-too-vague", "detail": "'Search for flights' lacks parameter hints", "impact": "Estimated +15% prompt routing accuracy" }
7    ],
8    "passed": [
9      { "rule": "valid-json-schema", "detail": "Schema is valid JSON Schema draft-07" },
10      { "rule": "clear-verb", "detail": "'Search' is an unambiguous action verb" }
11    ]
12  }
13}

Import Tools

POST/v1/tools/import⏱~5–30s

Import tool definitions from existing API specs. Supports OpenAPI/Swagger, MCP server tool lists, Postman Collections, and GraphQL schemas.

Parameters

Name	Type	Status	Description
`source`	`string`	Required	Source format: "openapi", "mcp", "postman", "graphql"
`sourceUrl`	`string`	Optional	URL to fetch the spec from
`content`	`string`	Optional	Raw spec content as string
`options.autoAnnotate`	`boolean`	true	Auto-detect annotations from HTTP methods

1curl -X POST https://api.web-mcp.net/v1/tools/import \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "source": "openapi",
6    "sourceUrl": "https://api.example.com/openapi.json",
7    "options": { "autoAnnotate": true }
8  }'

Response200 OK

1{
2  "importId": "import_R3mK7xP9",
3  "summary": { "totalEndpoints": 23, "suitable": 15, "needsReview": 5, "notSuitable": 3 },
4  "tools": [
5    { "status": "ready", "sourceEndpoint": "GET /api/flights/search", "confidence": 0.95 },
6    { "status": "needs_review", "sourceEndpoint": "POST /api/bookings", "confidence": 0.72 }
7  ]
8}

Generate Implementation Code

POST/v1/tools/{toolId}/code⏱~3–8s

Generate production-ready WebMCP registration code from a tool definition. Supports multiple frameworks and includes error handling, TypeScript types, and best practices.

Parameters

Name	Type	Status	Description
`toolId`	`string`	Required	Tool ID to generate code for
`framework`	`string`	Required	"vanilla", "react", "nextjs", "vue", "svelte", "webcomponent"
`language`	`string`	typescript	"typescript" or "javascript"
`options.includeTests`	`boolean`	true	Include unit test file
`options.includeTypes`	`boolean`	true	Generate TypeScript type definitions

1curl -X POST https://api.web-mcp.net/v1/tools/tool_Kx9mR3pQ/code \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "framework": "nextjs",
6    "language": "typescript",
7    "options": { "includeTests": true }
8  }'

Response200 OK

1{
2  "files": [
3    {
4      "path": "lib/webmcp/search-flights.ts",
5      "content": "// Generated by WebMCP\nimport { registerTool } from '@webmcp/sdk';\n\nexport function registerSearchFlights() {\n  ...",
6      "language": "typescript"
7    },
8    {
9      "path": "lib/webmcp/search-flights.test.ts",
10      "content": "// Auto-generated tests\nimport { registerSearchFlights } from './search-flights';\n...",
11      "language": "typescript"
12    }
13  ],
14  "framework": "nextjs",
15  "installCommand": "npm install @webmcp/sdk @webmcp/nextjs"
16}

_06

_06 testing

Testing & Quality

Test how AI agents interpret and invoke your WebMCP tools. From static schema validation to multi-model prompt coverage testing — these endpoints answer: “Will my tool actually get used correctly?”

Run Prompt Coverage Test

POST/v1/test/prompts🔄~30–120s

Send natural language prompts to multiple LLMs alongside your tool definitions and measure routing accuracy, parameter extraction, and hallucination rates.

Parameters

Name	Type	Status	Description
`tools`	`array`	Required	Tool IDs or inline definitions to test
`options.promptCount`	`number`	25	Auto-generated prompts per tool (max 200)
`options.models`	`string[]`	["gemini-2.0-flash"]	LLM models to test against
`options.runs`	`number`	1	Repetitions per prompt for stability scoring
`options.budget.maxCost`	`number`	Optional	Maximum cost in USD for this test run

1curl -X POST https://api.web-mcp.net/v1/test/prompts \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "tools": [{ "id": "tool_Kx9mR3pQ" }],
6    "options": {
7      "promptCount": 50,
8      "models": ["gemini-2.0-flash", "gpt-4o", "claude-sonnet-4"],
9      "runs": 3
10    }
11  }'

Response200 OK

1{
2  "id": "test_Px7mK3nQ",
3  "coverage": 0.87,
4  "totalPrompts": 150,
5  "byModel": {
6    "gemini-2.0-flash": { "accuracy": 0.91, "hallucinationRate": 0.03 },
7    "gpt-4o": { "accuracy": 0.88, "hallucinationRate": 0.05 },
8    "claude-sonnet-4": { "accuracy": 0.82, "hallucinationRate": 0.04 }
9  },
10  "stability": { "stablePrompts": 148, "flakyPrompts": 2 },
11  "cost": { "total": "$0.34" },
12  "duration": "47.3s"
13}

Run Auto-Generated Tests

POST/v1/test/auto⏱~10–30s

Generate and execute a comprehensive test suite from tool schemas alone — happy-path, boundary, type-mismatch, and adversarial test cases automatically.

Parameters

Name	Type	Status	Description
`tools`	`array`	Required	Tool IDs to test
`categories`	`string[]`	Optional	Test categories: happy-path, boundary, type-mismatch, adversarial

1curl -X POST https://api.web-mcp.net/v1/test/auto \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{ "tools": [{ "id": "tool_Kx9mR3pQ" }] }'

Response200 OK

1{
2  "id": "test_auto_Rx4mK9nQ",
3  "totalCases": 24,
4  "passed": 21,
5  "failed": 3,
6  "cases": [
7    { "category": "happy-path", "passed": true, "detail": "All required fields present" },
8    { "category": "adversarial", "passed": true, "detail": "Injection attempt correctly treated as literal string" }
9  ]
10}

Get Test Budget

GET/v1/test/budget⚡~100ms

Check your remaining LLM test budget for the current billing period. Use before running expensive multi-model prompt coverage tests.

Parameters

Name	Type	Status	Description
`includeHistory`	`boolean`	false	Include usage breakdown by test run

1curl "https://api.web-mcp.net/v1/test/budget" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "plan": "Team",
3  "period": { "start": "2026-02-01", "end": "2026-02-28" },
4  "budget": { "total": "$50.00", "used": "$18.42", "remaining": "$31.58" },
5  "usage": {
6    "promptCoverageTests": 12,
7    "autoTests": 34,
8    "simulations": 8,
9    "totalLLMCalls": 4230
10  },
11  "estimatedRunsRemaining": {
12    "promptCoverage50Prompts3Models": 18,
13    "autoTests": 95,
14    "multiModelSim": 42
15  }
16}

_07

_07 security

Security & Compliance

Scan for WebMCP-specific threat vectors: prompt injection, privacy leakage, misrepresentation of intent, and output injection. Enterprise security teams require these before approving any WebMCP implementation.

Run Security Scan

POST/v1/security/scan⏱~10–30s

Comprehensive security analysis against all known WebMCP threat vectors.

Parameters

Name	Type	Status	Description
`tools`	`array`	Required	Tool IDs or inline definitions to scan
`scanTypes`	`string[]`	Optional	injection, over-parameterization, misrepresentation, output-injection

1curl -X POST https://api.web-mcp.net/v1/security/scan \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{ "tools": [{ "id": "tool_Kx9mR3pQ" }] }'

Response200 OK

1{
2  "id": "security_Tx3mK8nQ",
3  "summary": { "totalFindings": 4, "critical": 1, "high": 1, "medium": 1, "low": 1, "score": 76 },
4  "findings": [
5    {
6      "severity": "critical",
7      "type": "misrepresentation",
8      "tool": "bookFlight",
9      "finding": "Tool processes payment but lacks requestUserInteraction()",
10      "remediation": "Add requestUserInteraction() before processing payment"
11    }
12  ]
13}

Generate Compliance Report

POST/v1/security/compliance🔄~30–60s

Auto-map tools to regulatory requirements and identify gaps. Supports GDPR, HIPAA, PCI-DSS.

Parameters

Name	Type	Status	Description
`tools`	`array`	Required	Tool IDs to analyze
`frameworks`	`string[]`	Required	"gdpr", "hipaa", "pci-dss"

1curl -X POST https://api.web-mcp.net/v1/security/compliance \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "tools": [{ "id": "tool_Kx9mR3pQ" }],
6    "frameworks": ["gdpr", "pci-dss"]
7  }'

Response200 OK

1{
2  "id": "compliance_Vx7mK2nQ",
3  "frameworks": {
4    "gdpr": { "status": "needs_remediation", "findings": 1 },
5    "pci-dss": { "status": "needs_remediation", "findings": 1 }
6  },
7  "exportUrl": "https://api.web-mcp.net/v1/security/compliance/compliance_Vx7mK2nQ/export?format=pdf"
8}

Enable Continuous Security Monitoring

POST/v1/security/monitor⚡~200ms

Enable automated security scanning on a schedule. Monitors for new vulnerabilities, schema drift, and compliance regression. Sends alerts via webhooks when issues are detected.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Site URL to monitor
`schedule`	`string`	daily	"hourly", "daily", "weekly"
`scanTypes`	`string[]`	Optional	Security scan types to include
`alertChannels`	`object`	Optional	Webhook URLs, Slack channels, or email addresses for alerts
`thresholds.minSecurityScore`	`number`	70	Alert when security score drops below this value

1curl -X POST https://api.web-mcp.net/v1/security/monitor \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "siteUrl": "https://travel-demo.bandarra.me",
6    "schedule": "daily",
7    "scanTypes": ["injection", "misrepresentation", "output-injection"],
8    "thresholds": { "minSecurityScore": 70 }
9  }'

Response200 OK

1{
2  "monitorId": "mon_Hx4mK9nQ",
3  "siteUrl": "https://travel-demo.bandarra.me",
4  "schedule": "daily",
5  "nextScanAt": "2026-02-10T00: 00: 00Z",
6  "status": "active",
7  "baseline": {
8    "securityScore": 76,
9    "findings": { "critical": 1, "high": 1, "medium": 1, "low": 1 }
10  }
11}

_07

_07 simulation

Agent Simulation

Simulate how real AI agents interact with your WebMCP tools before going to production. Multi-model comparison, description A/B testing, and workflow simulation.

Multi-Model Simulation

POST/v1/simulate/models⏱~15–45s

Send a natural language prompt to multiple LLMs simultaneously with your tool definitions. See how each model selects tools and extracts parameters.

Parameters

Name	Type	Status	Description
`prompt`	`string`	Required	Natural language prompt to test
`tools`	`array`	Required	Tool IDs to include
`models`	`string[]`	Required	LLM models to test against

1curl -X POST https://api.web-mcp.net/v1/simulate/models \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "prompt": "I need to fly from SFO to Tokyo next month, business class",
6    "tools": [{ "id": "tool_Kx9mR3pQ" }],
7    "models": ["gemini-2.0-flash", "gpt-4o", "claude-sonnet-4"]
8  }'

Response200 OK

1{
2  "id": "sim_Wx9mK4nQ",
3  "results": {
4    "gemini-2.0-flash": { "selectedTool": "searchFlights", "confidence": 0.96, "latency": "1.1s" },
5    "gpt-4o": { "selectedTool": "searchFlights", "confidence": 0.91, "latency": "2.0s" },
6    "claude-sonnet-4": { "selectedTool": "searchFlights", "confidence": 0.94, "latency": "1.7s" }
7  },
8  "consensus": { "allSelectedSameTool": true, "parameterAgreement": 0.87 },
9  "cost": "$0.02"
10}

Description A/B Test

POST/v1/simulate/ab🔄~30–60s

Test two different tool descriptions against the same prompt set to see which performs better. Data-driven optimization.

Parameters

Name	Type	Status	Description
`toolId`	`string`	Required	Base tool to test variants against
`variants.A.description`	`string`	Required	Variant A description
`variants.B.description`	`string`	Required	Variant B description
`promptCount`	`number`	50	Test prompts to generate

1curl -X POST https://api.web-mcp.net/v1/simulate/ab \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "toolId": "tool_Kx9mR3pQ",
6    "variants": {
7      "A": { "description": "Search for flights" },
8      "B": { "description": "Search for available flights between airports by date, passenger count, and cabin class. Accepts IATA codes or city names." }
9    },
10    "promptCount": 50
11  }'

Response200 OK

1{
2  "id": "ab_Bx3mK7nQ",
3  "winner": "B",
4  "results": {
5    "A": { "accuracy": 0.74, "hallucinationRate": 0.09 },
6    "B": { "accuracy": 0.92, "hallucinationRate": 0.02 }
7  },
8  "improvement": { "accuracyLift": "+24.3%", "hallucinationReduction": "-77.8%" },
9  "statisticalSignificance": 0.99
10}

Workflow Simulation

POST/v1/simulate/workflow🔄~30–90s

Simulate a multi-step agent workflow end-to-end. Define a sequence of tasks and see how agents chain your tools together. Identifies broken handoffs, missing tools, and parameter mismatches between steps.

Parameters

Name	Type	Status	Description
`workflow`	`object`	Required	Workflow definition with steps
`workflow.name`	`string`	Required	Workflow name (e.g., 'Book a round-trip flight')
`workflow.steps`	`array`	Required	Ordered steps with natural language descriptions
`tools`	`array`	Required	Tool IDs available during simulation
`model`	`string`	gemini-2.0-flash	LLM to use for simulation

1curl -X POST https://api.web-mcp.net/v1/simulate/workflow \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "workflow": {
6      "name": "Book round-trip flight",
7      "steps": [
8        "Search for flights from SFO to NRT next month",
9        "Select the cheapest business class option",
10        "Book the selected flight for 2 passengers"
11      ]
12    },
13    "tools": [{ "id": "tool_search" }, { "id": "tool_select" }, { "id": "tool_book" }],
14    "model": "gemini-2.0-flash"
15  }'

Response200 OK

1{
2  "id": "wfsim_Mx5nK8pQ",
3  "workflow": "Book round-trip flight",
4  "status": "completed",
5  "steps": [
6    { "step": 1, "tool": "searchFlights", "status": "success", "paramAccuracy": 0.95 },
7    { "step": 2, "tool": "selectFlight", "status": "success", "paramAccuracy": 0.88 },
8    { "step": 3, "tool": "bookFlight", "status": "warning", "issue": "Missing passenger count parameter" }
9  ],
10  "handoffs": [
11    { "from": 1, "to": 2, "dataFlow": "clean", "outputUsed": true },
12    { "from": 2, "to": 3, "dataFlow": "partial", "missingFields": ["passengerCount"] }
13  ],
14  "overallSuccess": false,
15  "recommendations": [
16    "Add 'passengerCount' to bookFlight description to improve parameter extraction"
17  ]
18}

Competitive Benchmark

POST/v1/simulate/benchmark🔄~60–120s

Compare your WebMCP implementation against competitors in the same industry. Anonymized scoring across tool quality, prompt coverage, security posture, and agent experience.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Your site URL
`competitors`	`string[]`	Optional	Competitor URLs to compare against (max 5). If omitted, uses industry benchmarks.
`industry`	`string`	auto	Industry vertical for benchmark context

1curl -X POST https://api.web-mcp.net/v1/simulate/benchmark \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "siteUrl": "https://travel-demo.bandarra.me",
6    "competitors": ["https://competitor1.com", "https://competitor2.com"],
7    "industry": "travel"
8  }'

Response200 OK

1{
2  "id": "bench_Nx7mK3pQ",
3  "yourSite": {
4    "url": "https://travel-demo.bandarra.me",
5    "overallScore": 82,
6    "rank": 1
7  },
8  "competitors": [
9    { "label": "Competitor A", "overallScore": 67, "rank": 2 },
10    { "label": "Competitor B", "overallScore": 41, "rank": 3 }
11  ],
12  "dimensions": {
13    "toolQuality": { "you": 91, "industryAvg": 58 },
14    "promptCoverage": { "you": 87, "industryAvg": 43 },
15    "security": { "you": 76, "industryAvg": 52 },
16    "agentExperience": { "you": 85, "industryAvg": 47 }
17  },
18  "industryPercentile": 92
19}

_08

_08 analytics

Analytics & Monitoring

Production analytics powered by the WebMCP SDK. These endpoints separate agent-initiated interactions from human traffic — the foundational capability for the agentic web.

Agent vs Human Traffic

GET/v1/analytics/traffic⚡~200ms

Get agent vs human traffic breakdown with trends over time.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Site URL
`startDate`	`string`	30 days ago	ISO 8601
`granularity`	`string`	day	day, week, month

1curl "https://api.web-mcp.net/v1/analytics/traffic?siteUrl=https://travel-demo.bandarra.me" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "summary": {
3    "totalPeriod": { "agent": 4200, "human": 14800, "agentPercent": 22.1 },
4    "growth": { "agentTraffic": "+34% month-over-month" }
5  }
6}

Revenue Attribution

GET/v1/analytics/revenue⚡~200ms

Track agent-driven conversions and revenue. The endpoint that justifies WebMCP investment to executives.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Site URL
`startDate`	`string`	Optional	ISO 8601 start date
`endDate`	`string`	Optional	ISO 8601 end date

1curl "https://api.web-mcp.net/v1/analytics/revenue?siteUrl=https://travel-demo.bandarra.me" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "revenue": {
3    "agentDriven": { "total": "$24,800", "transactions": 89 },
4    "humanDriven": { "total": "$156,200", "transactions": 423 },
5    "agentShare": "13.7%",
6    "agentGrowth": "+45% vs previous period"
7  },
8  "roi": { "webMCPCost": "$249/mo", "agentRevenue": "$24,800", "estimatedROI": "99.6x" }
9}

Tool Performance

GET/v1/analytics/tools⚡~200ms

See which tools agents use most, which get ignored, and which fail. Identifies your highest-impact optimization opportunities.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Site URL
`startDate`	`string`	30 days ago	ISO 8601 start date
`sort`	`string`	-invocations	Sort by: invocations, successRate, avgLatency

1curl "https://api.web-mcp.net/v1/analytics/tools?siteUrl=https://travel-demo.bandarra.me" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "tools": [
3    {
4      "name": "searchFlights",
5      "invocations": 3420,
6      "successRate": 0.96,
7      "avgLatency": "1.2s",
8      "topAgents": ["ChatGPT", "Gemini", "Claude"],
9      "trend": "+18% vs last period"
10    },
11    {
12      "name": "bookFlight",
13      "invocations": 890,
14      "successRate": 0.82,
15      "avgLatency": "3.1s",
16      "topAgents": ["ChatGPT", "Gemini"],
17      "trend": "+42% vs last period"
18    }
19  ],
20  "unused": ["cancelReservation"],

Agent Journeys

GET/v1/analytics/journeys⚡~200ms

Track complete agent interaction sequences — from initial tool discovery through multi-step workflows. Understand how agents chain your tools together in production.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Site URL
`startDate`	`string`	7 days ago	ISO 8601 start date
`minSteps`	`number`	2	Minimum journey steps to include

1curl "https://api.web-mcp.net/v1/analytics/journeys?siteUrl=https://travel-demo.bandarra.me&minSteps=2" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "topJourneys": [
3    {
4      "pattern": "searchFlights → selectFlight → bookFlight",
5      "count": 234,
6      "completionRate": 0.72,
7      "avgDuration": "4.2s",
8      "dropoff": { "step": "bookFlight", "rate": 0.28, "reason": "Missing passenger details" }
9    },
10    {
11      "pattern": "searchFlights → selectFlight",
12      "count": 412,
13      "completionRate": 0.91,
14      "avgDuration": "2.1s"
15    }
16  ],
17  "totalJourneys": 1847,
18  "avgStepsPerJourney": 2.3
19}

Error Diagnostics

GET/v1/analytics/errors⚡~200ms

Aggregated error analytics for agent interactions. See which tools fail most, common error patterns, and parameter extraction issues.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Site URL
`startDate`	`string`	7 days ago	ISO 8601 start date
`severity`	`string`	Optional	Filter by severity: critical, high, medium, low

1curl "https://api.web-mcp.net/v1/analytics/errors?siteUrl=https://travel-demo.bandarra.me" \
2  -H "Authorization: Bearer ar_live_sk_1234567890"

Response200 OK

1{
2  "summary": { "total": 147, "critical": 3, "high": 12, "medium": 48, "low": 84 },
3  "topErrors": [
4    {
5      "type": "PARAMETER_EXTRACTION_FAILED",
6      "tool": "bookFlight",
7      "count": 42,
8      "example": "Agent passed 'two' instead of 2 for passengerCount",
9      "fix": "Add 'type: integer' to passengerCount schema"
10    },
11    {
12      "type": "TOOL_TIMEOUT",
13      "tool": "searchFlights",
14      "count": 18,
15      "example": "Tool execution exceeded 30s timeout",
16      "fix": "Optimize backend query or increase timeout"
17    }
18  ],
19  "trend": "-23% vs previous period"
20}

Configure Alerts

POST/v1/analytics/alerts⚡~100ms

Set up automated alerts for analytics thresholds. Get notified when agent traffic drops, error rates spike, or revenue attribution changes significantly.

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Site URL to monitor
`rules`	`array`	Required	Alert rules with conditions and channels
`rules[].metric`	`string`	Required	Metric: agentTraffic, errorRate, revenue, toolSuccessRate, promptCoverage
`rules[].condition`	`string`	Required	"above", "below", "change_percent"
`rules[].threshold`	`number`	Required	Threshold value
`rules[].channel`	`string`	Required	"webhook", "email", "slack"

1curl -X POST https://api.web-mcp.net/v1/analytics/alerts \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "siteUrl": "https://travel-demo.bandarra.me",
6    "rules": [
7      { "metric": "errorRate", "condition": "above", "threshold": 0.10, "channel": "slack" },
8      { "metric": "agentTraffic", "condition": "change_percent", "threshold": -30, "channel": "email" }
9    ]
10  }'

Response200 OK

1{
2  "alertConfigId": "alert_Jx6mK4nQ",
3  "rules": [
4    { "id": "rule_1", "metric": "errorRate", "condition": "above 10%", "channel": "slack", "active": true },
5    { "id": "rule_2", "metric": "agentTraffic", "condition": "drops >30%", "channel": "email", "active": true }
6  ],
7  "status": "active"
8}

_09

_09 discovery

Discovery Hub

The public registry where AI agents discover WebMCP tools. Think NPM for WebMCP tools. Registering your tools here makes them discoverable by any AI agent.

Register Tools for Discovery

POST/v1/discovery/register⚡~200ms

Parameters

Name	Type	Status	Description
`siteUrl`	`string`	Required	Your website URL
`tools`	`array`	Required	Tool IDs to register
`listing.category`	`string`	Required	Category (travel, ecommerce, etc.)
`listing.tags`	`string[]`	Optional	Searchable tags

1curl -X POST https://api.web-mcp.net/v1/discovery/register \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "siteUrl": "https://travel-demo.bandarra.me",
6    "tools": [{ "id": "tool_Kx9mR3pQ" }],
7    "listing": { "category": "travel", "tags": ["flights", "booking"] }
8  }'

Response200 OK

1{
2  "listingId": "listing_Ex2mK9nQ",
3  "status": "pending_verification",
4  "verificationMethod": "dns_txt",
5  "verificationRecord": "webmcp-verify=listing_Ex2mK9nQ"
6}

Search Discovery Hub

GET/v1/discovery/search⚡~100ms • Public

Search the public tool registry. No auth required — designed to be called by AI agents to discover available tools.

Parameters

Name	Type	Status	Description
`q`	`string`	Optional	Natural language search (e.g., "book flights")
`category`	`string`	Optional	Filter by category
`minScore`	`number`	Optional	Minimum Agent Readiness Score
`verified`	`boolean`	Optional	Only verified listings

1curl "https://api.web-mcp.net/v1/discovery/search?q=book+flights&minScore=70"

Response200 OK

1{
2  "data": [
3    {
4      "listingId": "listing_Ex2mK9nQ",
5      "siteName": "TravelDemo",
6      "tools": [{ "name": "searchFlights", "quality": "high" }],
7      "score": 82,
8      "verified": true,
9      "monthlyAgentTraffic": 12400
10    }
11  ],
12  "total": 23
13}

_11

_11 copilot

AI Co-Pilot

Let AI help you build better WebMCP implementations. The Co-Pilot endpoints use LLMs to generate tool definitions from plain English, diagnose implementation issues, and explain WebMCP concepts — all via API.

Generate Tool from Description

POST/v1/copilot/generate⏱~3–8s

Describe what you want a tool to do in plain English, and the Co-Pilot generates a complete, validated WebMCP tool definition with JSON Schema, annotations, and best-practice descriptions.

Parameters

Name	Type	Status	Description
`description`	`string`	Required	Plain English description of what the tool should do
`context.siteUrl`	`string`	Optional	Your site URL for context-aware generation
`context.existingTools`	`string[]`	Optional	IDs of existing tools to avoid duplication
`options.variants`	`number`	1	Number of variants to generate (1–3)

1curl -X POST https://api.web-mcp.net/v1/copilot/generate \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "description": "A tool that searches restaurant menus by cuisine type, dietary restrictions, and price range. Should support filtering by vegan, gluten-free, and halal options.",
6    "options": { "variants": 2 }
7  }'

Response200 OK

1{
2  "variants": [
3    {
4      "name": "searchMenus",
5      "description": "Search restaurant menus by cuisine type, dietary restrictions (vegan, gluten-free, halal), and price range. Returns matching dishes with nutritional info and allergen warnings.",
6      "inputSchema": {
7        "type": "object",
8        "properties": {
9          "cuisine": { "type": "string", "description": "Cuisine type (e.g., italian, japanese, mexican)", "enum": ["italian", "japanese", "mexican", "indian", "thai", "american"] },
10          "dietary": { "type": "array", "items": { "type": "string", "enum": ["vegan", "vegetarian", "gluten-free", "halal", "kosher"] }, "description": "Dietary restriction filters" },
11          "priceRange": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }
12        },
13        "required": ["cuisine"]
14      },
15      "annotations": { "readOnlyHint": true },
16      "lintScore": 94,
17      "confidence": 0.92
18    }
19  ],
20  "cost": "$0.003"

Diagnose Issues

POST/v1/copilot/diagnose⏱~5–15s

Submit a scan result or tool definition and get AI-powered diagnosis of issues with specific, actionable fix suggestions. Like having a WebMCP expert review your implementation.

Parameters

Name	Type	Status	Description
`scanId`	`string`	Optional	Scan ID to diagnose
`toolId`	`string`	Optional	Tool ID to diagnose
`symptoms`	`string`	Optional	Describe the issue in plain English

1curl -X POST https://api.web-mcp.net/v1/copilot/diagnose \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "scanId": "scan_7xK2mP9q",
6    "symptoms": "Agents can find my searchFlights tool but keep failing on bookFlight. The prompt coverage for bookFlight is only 34%."
7  }'

Response200 OK

1{
2  "diagnosis": {
3    "rootCause": "bookFlight description is ambiguous — it says 'Book a flight' without specifying required parameters or constraints",
4    "issues": [
5      {
6        "severity": "high",
7        "issue": "Description doesn't mention required fields (passengerCount, paymentMethod)",
8        "impact": "Agents can't infer required parameters from the description alone",
9        "fix": "Update description to: 'Book a flight reservation for specified passengers with payment. Requires passenger count (1-9), selected flight ID from searchFlights, and payment method.'"
10      },
11      {
12        "severity": "medium",
13        "issue": "Missing requestUserInteraction() annotation for financial transaction",
14        "impact": "Security score penalty and agents may skip confirmation step",
15        "fix": "Add annotations: { destructiveHint: true, idempotentHint: false }"
16      }
17    ],
18    "estimatedImpact": {
19      "promptCoverage": "34% → ~78% (estimated)",
20      "securityScore": "+12 points"

Explain WebMCP Concept

POST/v1/copilot/explain⚡~2–5s

Get plain-English explanations of WebMCP concepts, scoring criteria, or best practices. Perfect for onboarding new team members or understanding why a specific recommendation was made.

Parameters

Name	Type	Status	Description
`topic`	`string`	Required	Concept or question to explain
`context.scanId`	`string`	Optional	Scan ID for contextual explanations
`level`	`string`	intermediate	"beginner", "intermediate", "expert"

1curl -X POST https://api.web-mcp.net/v1/copilot/explain \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "topic": "Why did my security score drop after adding the bookFlight tool?",
6    "context": { "scanId": "scan_7xK2mP9q" },
7    "level": "intermediate"
8  }'

Response200 OK

1{
2  "explanation": "Your security score dropped from 91 to 76 because the bookFlight tool processes a financial transaction (payment) but doesn't include the requestUserInteraction() call. WebMCP requires explicit user confirmation for any action that involves money, personal data modification, or irreversible operations. This is the #1 security finding across all WebMCP implementations.",
3  "relatedDocs": [
4    { "title": "Security Best Practices", "url": "https://web-mcp.net/docs/security" },
5    { "title": "requestUserInteraction()", "url": "https://web-mcp.net/docs/api/user-interaction" }
6  ],
7  "cost": "$0.002"
8}

_10

_10 webhooks

Webhooks & Events

Receive real-time notifications when things happen in your WebMCP account. Essential for CI/CD pipelines, monitoring dashboards, and event-driven architectures.

Available Events

Category	Event	Description
`Scanning`	scan.completed	Scan finished successfully
`Scanning`	scan.failed	Scan encountered an error
`Scoring`	score.changed	Score crossed a threshold or changed by >5 points
`Scoring`	score.regressed	Score decreased from previous scan
`Tools`	tool.created	New tool definition created
`Tools`	tool.updated	Tool definition modified
`Tools`	tool.deleted	Tool definition soft-deleted
`Testing`	test.completed	Test run finished
`Testing`	test.coverage.below_threshold	Prompt coverage dropped below minimum
`Security`	security.finding.critical	New critical security finding
`Security`	security.finding.high	New high-severity finding
`Security`	security.compliance.failed	Compliance check failed
`Analytics`	analytics.anomaly	Traffic or error anomaly detected
`Analytics`	analytics.alert.triggered	Custom alert rule triggered

Signature Verification

Every webhook payload is signed with your webhook secret using HMAC-SHA256. Always verify signatures before processing events to prevent replay attacks.

1300">"text-blue-400">import crypto 300">"text-blue-400">from 300">'crypto';
2 
3300">"text-blue-400">function verifyWebhookSignature(payload, signature, secret) {
4  300">"text-blue-400">const expected = crypto
5    .createHmac(300">'sha256', secret)
6    .update(payload, 300">'utf8')
7    .digest(300">'hex');
8 
9  300">"text-blue-400">const sig = signature.replace(300">'sha256=', 300">'');
10  300">"text-blue-400">return crypto.timingSafeEqual(
11    Buffer.300">"text-blue-400">from(sig, 300">'hex'),
12    Buffer.300">"text-blue-400">from(expected, 300">'hex')
13  );
14}
15 
16300">"text-white/25 italic">// Express middleware
17app.post(300">'/webhooks/webmcp', (req, res) => {
18  300">"text-blue-400">const signature = req.headers[300">'x-webmcp-signature'];
19  300">"text-blue-400">const isValid = verifyWebhookSignature(
20    JSON.stringify(req.body),
21    signature,
22    process.env.WEBHOOK_SECRET
23  );
24 
25  300">"text-blue-400">if (!isValid) 300">"text-blue-400">return res.status(401).send(300">'Invalid signature');
26  300">"text-white/25 italic">// Process event...
27  res.status(200).send(300">'OK');
28});

Delivery & Retry Policy

Aspect	Detail
`Timeout`	Your endpoint must respond within 5 seconds
`Retries`	3 attempts with exponential backoff (10s, 60s, 300s)
`Success`	Any 2xx response is considered successful delivery
`Failure`	After 3 failed attempts, webhook is marked as failing
`Disable`	After 7 consecutive days of failures, webhook is automatically disabled
`Headers`	X-WebMCP-Signature, X-WebMCP-Event, X-WebMCP-Delivery-ID

Create Webhook

POST/v1/webhooks⚡~100ms

Subscribe to events with filtering and signature verification.

Parameters

Name	Type	Status	Description
`url`	`string`	Required	Your webhook endpoint URL (must be HTTPS)
`events`	`string[]`	Required	Events to subscribe to
`secret`	`string`	Required	Signing secret for payload verification

1curl -X POST https://api.web-mcp.net/v1/webhooks \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "url": "https://your-server.com/webhooks/webmcp",
6    "events": ["scan.completed", "score.changed", "security.finding.critical"],
7    "secret": "whsec_your_signing_secret_here"
8  }'

Response200 OK

1{
2  "id": "wh_Zx3mK7nQ",
3  "url": "https://your-server.com/webhooks/webmcp",
4  "events": ["scan.completed", "score.changed", "security.finding.critical"],
5  "active": true,
6  "createdAt": "2026-02-09T15: 00: 00Z"
7}

Test Webhook

POST/v1/webhooks/{webhookId}/test⚡~1–3s

Send a test event to your webhook endpoint to verify it's configured correctly. Returns the response from your server.

Parameters

Name	Type	Status	Description
`webhookId`	`string`	Required	Webhook ID to test
`event`	`string`	test.ping	Event type to simulate

1curl -X POST "https://api.web-mcp.net/v1/webhooks/wh_Zx3mK7nQ/test" \
2  -H "Authorization: Bearer ar_live_sk_1234567890" \
3  -H "Content-Type: application/json" \
4  -d '{ "event": "scan.completed" }'

Response200 OK

1{
2  "delivered": true,
3  "responseCode": 200,
4  "responseTime": "142ms",
5  "payload": {
6    "event": "scan.completed",
7    "data": { "scanId": "scan_test_xxx", "score": 82, "url": "https://example.com" },
8    "timestamp": "2026-02-09T15: 30: 00Z"
9  }
10}

_13

_13 rate_limits

Rate Limits & Usage

All rate limits are per API key on a rolling window basis. The SDKs handle rate limiting automatically with retry + backoff. If you're building direct integrations, implement the same pattern using the response headers.

Limits by Plan

Plan	Requests/min	Burst (10s)	Concurrent	Scans/day	Deep Scans/day	LLM Budget/mo
`Free`	10	5	2	5	1	$0
`Solo ($29)`	60	20	5	20	5	$5
`Team ($249)`	300	100	15	100	25	$50
`Business ($749)`	1,000	300	50	500	100	$200
`Enterprise`	Custom	Custom	Custom	Custom	Custom	Custom

Rate Limit Headers

Every response includes rate limit information. Use these headers to implement client-side rate limiting:

1X-RateLimit-Limit: 300          "text-white/25 italic"># Max requests per minute
2X-RateLimit-Remaining: 247      "text-white/25 italic"># Remaining requests in window
3X-RateLimit-Reset: 1739111460   "text-white/25 italic"># Unix timestamp when limit resets
4X-RateLimit-Resource: api       "text-white/25 italic"># Which limit applies (api, scan, llm)
5Retry-After: 3                  "text-white/25 italic"># Seconds to wait (only on 429)

Handling 429 Responses

When rate limited, implement exponential backoff. The SDK handles this automatically. For direct API calls:

1300">"text-blue-400">async 300">"text-blue-400">function apiCallWithRetry(fn, maxRetries = 3) {
2  300">"text-blue-400">for (300">"text-blue-400">let attempt = 0; attempt <= maxRetries; attempt++) {
3    try {
4      300">"text-blue-400">return 300">"text-blue-400">await fn();
5    } catch (err) {
6      300">"text-blue-400">if (err.status === 429 && attempt < maxRetries) {
7        300">"text-blue-400">const retryAfter = err.headers[300">'retry-after'] || Math.pow(2, attempt);
8        300">"text-blue-400">await 300">"text-blue-400">new Promise(r => setTimeout(r, retryAfter * 1000));
9        continue;
10      }
11      throw err;
12    }
13  }
14}

_14

_14 sdks

SDKs & Libraries

Official SDKs handle authentication, retries, pagination, rate limiting, and type safety automatically. All SDKs are open-source with full TypeScript/type-hint support.

Framework Integrations

Framework	Package	Features
`Next.js`	@webmcp/nextjs	App Router middleware, server actions, ISR-compatible
`React`	@webmcp/react	Hooks (useWebMCP, useScan), context provider
`Vue`	@webmcp/vue	Composables, plugin system
`Svelte`	@webmcp/svelte	Stores, SvelteKit integration
`Express`	@webmcp/express	Middleware, webhook verification
`Python / Django`	webmcp[django]	Django middleware, template tags
`Python / FastAPI`	webmcp[fastapi]	Dependency injection, Pydantic models
`Go`	webmcp-go	Standard library HTTP compatible
`Browser Extension`	@webmcp/extension	Chrome/Firefox extension for visual scanning
`CLI`	@webmcp/cli	Terminal commands for CI/CD and local development

JavaScript / TypeScript SDK

1300">"text-blue-400">import WebMCP 300">"text-blue-400">from 300">'@webmcp/sdk';
2 
3300">"text-blue-400">const ar = 300">"text-blue-400">new WebMCP(300">'ar_live_sk_1234567890');
4 
5300">"text-white/25 italic">// Scan a site
6300">"text-blue-400">const scan = 300">"text-blue-400">await ar.scans.create({ url: 300">'https:300">"text-white/25 italic">//example.com', deep: 300">"text-blue-400">true });
7console.log(300">`Score: ${scan.score}/100`);
8 
9300">"text-white/25 italic">// List tools
10300">"text-blue-400">const tools = 300">"text-blue-400">await ar.tools.list({ siteUrl: 300">'https:300">"text-white/25 italic">//example.com' });
11 
12300">"text-white/25 italic">// Run prompt coverage test
13300">"text-blue-400">const test = 300">"text-blue-400">await ar.tests.promptCoverage({
14  tools: tools.data.map(t => ({ id: t.id })),
15  models: [300">'gemini-2.0-flash', 300">'gpt-4o'],
16  promptCount: 50
17});

Python SDK

1300">"text-blue-400">import webmcp
2 
3client = webmcp.Client(300">"ar_live_sk_1234567890")
4 
5scan = client.scans.create(url=300">"https://example.com", deep=300">"text-blue-400">True)
6print(f300">"Score: {scan.score}/100")
7 
8tools = client.tools.list(site_url=300">"https://example.com")
9 
10test = client.tests.prompt_coverage(
11    tools=[{300">"id": t.id} 300">"text-blue-400">for t 300">"text-blue-400">in tools.data],
12    models=[300">"gemini-2.0-flash", 300">"gpt-4o"],
13    prompt_count=50
14)

CLI

1"text-white/25 italic"># Scan a URL
2webmcp-cli scan https://example.com
3 
4"text-white/25 italic"># Deep scan with multi-model testing
5webmcp-cli scan https://example.com --deep --models gemini,gpt4o,claude
6 
7"text-white/25 italic"># Lint a tool definition
8webmcp-cli lint tool.json
9 
10"text-white/25 italic"># CI/CD gate
11webmcp-cli ci --url https://staging.example.com --min-score 75
12 
13"text-white/25 italic"># Generate tool from description
14webmcp-cli generate "A tool that searches restaurant menus"