API for Agents

Query the WebMCP directory.

Read-only JSON API for agents. List WebMCP-enabled sites, fetch their tools and input schemas, or check whether a given URL exposes any.

Try /api/v1/sites OpenAPI spec Directory stats

TL;DR

Base URL https://webmcp.com. JSON responses, no auth, CORS open (Access-Control-Allow-Origin: *). For a one-shot probe of an arbitrary URL, use /api/v1/lookup?url=….

Deprecation (2026-07-03). Tool kind values were renamed read/write/action → answer/act/transact — displayed on webmcp.com as Answer, Action, and Sensitive Action. The old values are no longer emitted or accepted by the kind filter. See the OpenAPI changelog and Tool categories.

GET /api/v1/lookup

Probe an arbitrary URL

Given any URL, check the stored directory and Shopify index. A directory match returns supported: true and its site record. An index-only Shopify match returns platform: "shopify", platformUrl, and the shared toolCount, without a site record. Follow platformUrl for shared schemas; stores may add tools. This does not perform a live verification. The host is extracted, www. stripped, and path-scoped demos (e.g. googlechromelabs.github.io/webmcp-tools/demos/*) are matched by URL prefix.

Param	Type	Description
url	string	Any URL on the page being probed. The host is extracted; path-scoped demos match by prefix.
host	string	Alternative to `url`. `www.` is stripped before matching.

Example — direct host match

GEThttps://webmcp.com/api/v1/lookup?url=https://store.nekuda.ai/checkout

{ "ok": true, "supported": true, "host": "store.nekuda.ai", "matchedHost": "store.nekuda.ai", "site": { "host": "store.nekuda.ai", "url": "https://store.nekuda.ai", "desc": "AI-native demo storefront", "type": "demo", "apiSurface": "spec", "toolCount": 13, "tools": [ /* 13 tools with inputSchema */ ] } }

Example — not supported

GEThttps://webmcp.com/api/v1/lookup?url=https://example.com

{ "ok": true, "supported": false, "host": "example.com", "message": "no WebMCP tools registered for this host in webmcp.com directory" }

GET /api/v1/sites

List & filter sites

Returns directory entries. All params are optional and combinable. Use fields to control response size: full includes every tool's inputSchema, summary drops schemas, minimal returns only name/kind/impl/description.

Curated Shopify entries remain in this directory. Search the additional store index with the Shopify store endpoint; it is excluded from bulk directory and tool listings.

Param	Type	Description
type	live \| demo \| all	Filter by site type. Defaults to all.
q	string	Substring search across host, description, URL, and every tool name/description.
tool	string	Return only sites that expose a tool whose name contains this substring.
kind	answer \| act \| transact	Filter sites by tool category (Answer / Action / Sensitive Action). Repeat to OR (e.g. `kind=answer&kind=act`).
impl	imperative \| declarative	Filter by tool implementation style.
apiSurface	spec \| polyfill \| mixed	Filter by which API surface the site uses to register tools. `spec` = WICG `registerTool` or declarative DOM. `polyfill` = `@mcp-b/webmcp-polyfill` `provideContext` extension. `mixed` = both. Repeat to OR.
fields	full \| summary \| minimal	Response shape. Defaults to `full`.
limit	integer	Max sites to return. Default 100, max 500.
offset	integer	Pagination offset.

Example — live sites only, summary payload

GEThttps://webmcp.com/api/v1/sites?type=live&fields=summary

Example — sites that expose a checkout tool

GEThttps://webmcp.com/api/v1/sites?tool=checkout&fields=minimal

GET /api/v1/sites/{host}

Get a single site

Returns the full record for one directory entry, including every tool with its JSON Schema. host is the directory key — www. is stripped before matching.

GEThttps://webmcp.com/api/v1/sites/store.nekuda.ai

GET /api/v1/sites/{host}/tools

List tools for a site

Returns the tools array only — no surrounding site metadata.

GEThttps://webmcp.com/api/v1/sites/store.nekuda.ai/tools

GET /api/v1/sites/{host}/tools/{tool}

Get one tool definition

Returns a single tool's full record including its inputSchema.

GEThttps://webmcp.com/api/v1/sites/store.nekuda.ai/tools/add_to_cart

{ "ok": true, "host": "store.nekuda.ai", "url": "https://store.nekuda.ai", "tool": { "name": "add_to_cart", "kind": "act", "impl": "imperative", "page": "/cart", "description": "Add a product to the shopping cart…", "inputSchema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The product ID to add" }, "quantity": { "type": "number", "description": "Number of items (default 1)" } }, "required": ["product_id"] } } }

GET /api/v1/tools

Search every tool across every site

Flat search across all tools in the directory. Each result carries the host and URL it belongs to.

Param	Type	Description
q	string	Substring match against tool name and description.
kind	answer \| act \| transact	Filter by category (Answer / Action / Sensitive Action). Repeat to OR.
impl	imperative \| declarative	Filter by implementation style.
limit / offset	integer	Pagination — default 100, max 500.

GEThttps://webmcp.com/api/v1/tools?q=cart&kind=act

GET /api/v1/stats

Aggregate directory stats

Useful for status dashboards. Returns totals plus a breakdown by tool kind and implementation, and the top 10 sites by tool count. sites, tools, and breakdowns cover directory records. platforms.shopify counts indexed stores; totalSites adds both sets and removes overlapping hosts. When the index is unavailable, the imported count is used and overlap assumes the importer included all curated Shopify stores. These counts describe index coverage.

GEThttps://webmcp.com/api/v1/stats

{ "ok": true, "version": 1, "sites": 18, "liveSites": 3, "demoSites": 15, "tools": 66, "byKind": { "act": 33, "answer": 26, "transact": 7 }, "byImpl": { "imperative": 58, "declarative": 8 }, "topSitesByToolCount": [ /* 10 entries */ ] }

GET /api/v1/platforms/shopify

One shared Shopify toolkit

Shopify stores share a core WebMCP implementation and may add their own tools. This endpoint returns the shared tools with input schemas, apiSurface, sentinelHost, and storeCount. Tools follow the latest directory snapshot of the reference store, falling back to the imported tool snapshot.

updatedAt is the store index import date. toolsUpdatedAt is when the reference tools were captured, or null if unknown. The count describes indexed hosts, not individual live verification. Returns 404 if platform metadata is unavailable.

source records the import provenance separately; indexSha256 identifies the artifact and indexReady reports whether it is available. The September 9, 2026 snapshot contains 833,707 hosts: 833,690 source hosts plus 17 curated additions. Source checks dated July 8-14 recorded 814,365 static WebMCP confirmations and 19,325 browser tool captures. The shared Alo Yoga toolkit was captured again on September 9; this does not mean every indexed store was rechecked then.

GEThttps://webmcp.com/api/v1/platforms/shopify

GET /api/v1/platforms/shopify/stores

Find a Shopify store

Pass q with 3-100 characters to search indexed hostnames by substring, ignoring case. Queries are trimmed. Returns up to 20 hosts in results, plus query, matchCount, matchCountTruncated, and limit. The match count stops at 5,000; matchCountTruncated: true means 5,000 or more.

There is no pagination or bulk export. Curated Shopify records remain in the regular directory APIs. Index membership is not a live verification; use /api/v1/lookup?host=… for a stored record and the shared toolkit link. Non-directory lookups share the search quotas below.

Invalid queries return 400; an unavailable index returns 503. Search and non-directory lookups share limits: 30 requests per IP per 10 minutes, 50 per IP per UTC day, and 1,000 globally per UTC day. Operators can lower these ceilings. Invalid and cached searches count. Limits persist across restarts and instances; if quota storage is unavailable, requests return 503. A 429 response includes Retry-After and JSON retryAfter in seconds. The OpenAPI spec reports the configured limit.

GEThttps://webmcp.com/api/v1/platforms/shopify/stores?q=alo

GET /api/openapi.json

OpenAPI 3.1 spec

The full machine-readable contract for this API. Works with Swagger UI, OpenAPI codegen, or a ChatGPT action.

GEThttps://webmcp.com/api/openapi.json

Built and maintained by nekuda. Missing a site? Submit it on the directory.