API Reference

Overview

All API endpoints accept and return JSON. Read endpoints are fully public — no API key or auth required. Write endpoints require you to be signed in via the registry web interface; requests must include the session cookie set at sign-in.

The registry is designed for use by AI agents, browser extensions, and developer tooling that need to discover WebMCP tool contracts at runtime.

Base URL

https://webmcp-registry.dev

All paths below are relative to this base. Responses are always application/json.

Authentication

Public read endpoints require no authentication. Write and delete endpoints — POST /api/submit, POST /api/verify, DELETE /api/domain/:domain, and DELETE /api/tool/:domain/:name — require an API key and domain ownership.

API keys

Generate API keys in your dashboard. Each key is shown exactly once at creation — store it securely. Keys can be revoked at any time. Maximum 3 active keys per account.

Pass the key in the Authorization header on every request:

POST https://webmcp-registry.dev/api/submit
Authorization: Bearer wmcp_your_key_here
Content-Type: application/json

{ "domain": "example.com", "tools": [ ... ] }

Keys are scoped to your account. All ownership rules still apply — you can only submit, verify, or delete domains that belong to your account.

Search tools

Returns a list of tool contracts matching the query. Searches across tool names and descriptions using case-insensitive substring matching. If no query is provided, returns the 50 most recently added tools.

Query parameters

Example

GET https://webmcp-registry.dev/api/tools?q=flights&verified=true

{
  "results": [
    {
      "domain": "example.com/app",
      "verified": true,
      "tool": {
        "name": "searchFlights",
        "description": "Searches for flights with the given parameters.",
        "inputSchema": { "type": "object", "properties": { ... } },
        "specVersion": "0.1"
      }
    }
  ],
  "total": 1
}

Get domain

Returns a domain record and all of its active tool contracts. The :domain segment is the full registered domain path, which may include URL path segments (e.g. example.com/app/demo).

Example

GET https://webmcp-registry.dev/api/domain/example.com/app

{
  "domain": "example.com/app",
  "verified": true,
  "verifiedAt": "2025-06-01T12:00:00.000Z",
  "tools": [
    {
      "name": "add-todo",
      "description": "Add a new item to the todo list.",
      "inputSchema": { "type": "object", "properties": { ... } },
      "outputSchema": null,
      "specVersion": "0.1",
      "updatedAt": "2025-06-01T12:00:00.000Z"
    }
  ]
}

Get tool

Returns the full contract for a single tool, including its input schema, optional output schema, and schema change history.

Example

GET https://webmcp-registry.dev/api/tool/example.com/app/add-todo

{
  "domain": "example.com/app",
  "verified": true,
  "name": "add-todo",
  "description": "Add a new item to the todo list.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "The todo item text." }
    },
    "required": ["text"]
  },
  "outputSchema": null,
  "specVersion": "0.1",
  "createdAt": "2025-06-01T12:00:00.000Z",
  "updatedAt": "2025-06-01T12:00:00.000Z",
  "history": []
}

Submit tools

Registers one or more tool contracts for a domain. Requires authentication. If the domain already exists and is owned by your account, the tools are upserted (existing tools are versioned before being overwritten). If the domain does not exist, it is created and assigned to your account.

Request body

{
  "domain": "example.com/app",
  "tools": [
    {
      "name": "add-todo",
      "description": "Add a new item to the todo list.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "text": { "type": "string" }
        },
        "required": ["text"]
      }
    }
  ]
}

Response

{
  "domainId": "uuid",
  "verificationToken": "abc123...",
  "verified": false,
  "toolsSubmitted": 1
}

After submission, add a DNS TXT record at the root of your domain containing webmcp-verify={verificationToken}, then call POST /api/verify to get the verified badge.

Verify domain

Checks for the DNS TXT record and marks the domain as verified if found. Requires authentication and domain ownership.

Request body

{ "domain": "example.com/app" }

Response

{ "verified": true, "message": "Domain verified successfully." }

DNS propagation can take up to 48 hours. If the record is not found, the response returns verified: false with a message — retry after propagation completes.

Delete domain

Permanently deletes a domain and all of its tools and schema history. Requires authentication and ownership of the domain. This action is irreversible.

Example

DELETE https://webmcp-registry.dev/api/domain/example.com/app

{ "deleted": true }

Delete tool

Permanently deletes a single tool and its schema version history from a domain. The domain itself is not affected. Requires authentication and ownership of the domain.

Example

DELETE https://webmcp-registry.dev/api/tool/example.com/app/add-todo

{ "deleted": true }

Tool contract schema

All tools submitted to the registry must conform to the WebMCP tool contract format.

Minimal example

{
  "name": "get-status",
  "description": "Returns the current application status.",
  "inputSchema": {
    "type": "object",
    "properties": {}
  }
}

Full example

{
  "name": "search-products",
  "description": "Search the product catalog by keyword and optional filters.",
  "specVersion": "0.1",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search keyword"
      },
      "maxPrice": {
        "type": "number",
        "description": "Maximum price filter"
      }
    },
    "required": ["query"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "results": {
        "type": "array",
        "items": { "type": "object" }
      }
    }
  }
}

Errors

All error responses use standard HTTP status codes with a JSON body:

{ "error": "Human-readable error message." }