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. 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, return whether the site exposes WebMCP tools and — if so — its full record. 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.

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. 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. 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.

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/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.