Search

The public server registry and template catalog accept RouterMCP's shared literal query syntax. Other RouterMCP surfaces retain their existing behavior until their adapters are released. See the Public Catalog API reference for complete endpoint contracts.

Legacy public registry filters

GET /api/registry keeps its existing parameter mode when query is omitted:

Legacy requests return {items}. The search parameter retains case-insensitive SQL wildcard behavior over server and publisher titles. Invalid types, booleans, ranges, and overlong values return HTTP 400.

Expressive public catalog queries

Use query with /api/registry, or use /api/templates. Expressive registry requests cannot combine query with the legacy search, publisher, type, tag, boolean filters, requireTools, or offset. Templates accept query only with cursor and limit.

Both endpoints return {items,count,nextCursor,warnings,coverage}. count is the number of items on the returned page, not a total. limit defaults to 20 and may be set from 1 to 50. Follow nextCursor to continue through the full matching set; omit the cursor to restart. A stale cursor returns HTTP 409 with code: "CURSOR_STALE" and restart: true; clients should restart from the first page and replace the displayed results.

Whitespace-separated terms must all match. Double quotes group a literal phrase. Prefix a term or qualifier with - to exclude it. Repeated positive values for one qualifier match any listed value; different qualifiers must all match.

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

Registry queries search publisher/server identifiers and titles and tags; supported qualifiers are transport (http, sse, stdio), tag, publisher, verified, and featured. Template queries search slug/title, category, role, description, tags, and related server names; supported qualifiers are category (role, use-case, starter) and tag. The catalog result type is fixed by each endpoint. type:registry and type:template may be written explicitly for clarity.

Queries are limited to 2,048 Unicode code points, 8,192 UTF-8 bytes, and 64 clauses. Quoted text supports escaped quotes and backslashes. Search text is normalized to NFC and lowercased using Unicode rules while preserving accents. Matching is literal; it does not stem words or remove accents. % and _ are ordinary characters in expressive mode. Unknown qualifiers, unsupported filters, invalid enum values, and unclosed quotes return HTTP 400 with a diagnostic code and optional clause span. AND, OR, and parentheses are unsupported. NUL characters (U+0000) are rejected with a syntax diagnostic and source span.

Expressive catalog results include allowlisted public metadata only. They omit server configuration, tool schemas, and OAuth data. Search helps a caller choose a server or template; it does not grant permission to execute a tool.

Other search surfaces

Natural-language task ranking remains separate from explicit query syntax. Hosted and CLI task ranking retain their established scoring profiles and stable tie ordering. Explicit query syntax always uses literal matching. Search results help a caller choose a tool; every execution still performs its own caller-scope and permission checks.