Public Catalog API

The public catalog endpoints do not require authentication. Expressive registry query results and template search results include public metadata only; they exclude server configuration, tool schemas, and OAuth credentials. The legacy registry parameter mode retains its existing registry record fields; the expressive mode's metadata-only guarantee does not apply to it.

Registry

GET /api/registry retains its legacy parameter mode and { "items": [...] } response. Its default limit is 500, with offset pagination up to 10,000. The legacy search parameter uses case-insensitive substring matching over server and publisher titles; % and _ keep their existing SQL wildcard behavior. Legacy filters include publisher, type, tag, verified, featured, and requireTools.

The additive expressive mode uses query, cursor, and an optional limit from 1 to 50 (default 20). Do not combine query with legacy filters or offset.

Browsing without text terms retains featured, verified, then title ordering, including when transport, tag, or publisher qualifiers filter the catalog. Text searches use relevance ordering.

GET /api/registry?query=%22file%20search%22%20transport:http&limit=20

The response keeps the items key and adds a page count, continuation cursor, warnings, and coverage. count is the number of returned rows on this page, not the complete result total.

{
  "items": [
    {
      "id": "registry-id",
      "publisherName": "example",
      "publisherTitle": "Example",
      "serverName": "files",
      "serverTitle": "File Search",
      "serverType": "http",
      "tags": ["files"],
      "verified": true,
      "featured": false,
      "iconUrl": null,
      "repoUrl": "https://github.com/example/files",
      "docsUrl": null,
      "websiteUrl": null
    }
  ],
  "count": 1,
  "nextCursor": null,
  "warnings": [],
  "coverage": { "kind": "complete" }
}

Templates

GET /api/templates accepts query, cursor, and limit (1–50, default 20). It supports literal text over template slug, title, description, role, category, tags, and related server names, plus category and tag qualifiers.

Browsing without text terms retains creation-time ordering with an ID tie-breaker, including category- or tag-only filters. Text searches use relevance ordering.

GET /api/templates?query=category:starter%20%22database%22

The response uses the same page envelope as expressive registry search. Template items include their role, difficulty, estimated setup time, tags, and related server names; configuration and OAuth fields are excluded.

Query syntax

Whitespace-separated terms are literal substring clauses and all must match. Double quotes group a phrase; quotes and backslashes can be escaped inside a phrase. Prefix a text or qualifier clause with - to exclude matches. Repeated positive values for one qualifier are alternatives; different qualifiers must all match.

"search files" -archived
transport:http tag:filesystem verified:true
category:starter tag:database

The registry surface supports transport, tag, publisher, verified, and featured. The template surface supports category and tag. In each surface the result type is fixed. type or entity is available for consistency but cannot select another catalog. Unknown or unsupported qualifiers return HTTP 400 with a diagnostic code and optional clause span. A stale cursor returns HTTP 409 with code: "CURSOR_STALE" and restart: true; restart the same query without the cursor and replace the current page with the new first page.