MCP Catalog API

A public, read-only HTTP API over the crawled MCP catalog. It powers this site and is open for anyone to build on - no key, no signup. Every response is JSON in a single stable envelope.

Base URL

https://api.agentage.io/api/mcp

Machine-readable spec: openapi.json (OpenAPI 1.0.0). For agents, see llms.txt.

Endpoints

GET/icons/{slug}

The cached 128x128 webp icon for a server (registry-provided or owner-avatar source, re-encoded). Immutable per slug: long-cached and exempt from the per-caller rate limit. Returns 404 when no icon is cached.

Param	In		Type	Description
slug	path	required	string (1-200)	Catalog server slug.

curl "https://api.agentage.io/api/mcp/icons/example-server" -o icon.webp

GET/mcps

Paginated, filterable, sortable server list. All filters AND-combine.

Param	In		Type	Description
page	query	optional	integer	Page number, 1-based.
limit	query	optional	integer (1-100)	Items per page (1-100).
type	query	optional	array	Filter by package registry type; "remote" means the server has a hosted endpoint. An unknown value is a 400.
category	query	optional	array	Filter by AI-taxonomy label, exactly as listed by /api/categories. An unknown value is a 400 naming that endpoint.
language	query	optional	array	Filter by GitHub language (exact; an unknown value matches nothing, not a 400).
license	query	optional	array	Filter by GitHub license name ("MIT License") or SPDX id ("MIT"); an unknown value matches nothing, not a 400.
sort	query	optional	popularity \| name \| stars \| updated \| downloads \| trending	Sort order: popularity desc (default composite rank), name asc, stars/updated/downloads/trending desc (trending = stars gained this week), with a slug asc tie-break.
view	query	optional	full \| card

curl "https://api.agentage.io/api/mcp/mcps?type=npm&category=Security&sort=stars&limit=24"

GET/mcps/{slug}

Single server detail, merging its README and captured tools when present.

Param	In		Type	Description
slug	path	required	string (1-200)	Catalog server slug.

curl "https://api.agentage.io/api/mcp/mcps/example-server"

GET/v0.1/servers

Official MCP-registry-compatible read alias (subregistry pattern). Returns the { servers: [{ server, _meta }], metadata } envelope - NOT the house { success, data, meta } shape - so registry clients consume it directly. Each entry carries our enrichment under _meta["io.agentage.catalog/v0"]. Cursor-paginated; supports updated_since + substring search. Only the latest version is stored, so version is accepted for compatibility and ignored. See https://modelcontextprotocol.io/registry/registry-aggregators.

Param	In		Type	Description
cursor	query	optional	string (1-200)	Opaque pagination cursor from a prior page metadata.nextCursor; pass it back verbatim.
limit	query	optional	integer (1-100)	Max servers per page (1-100).
updated_since	query	optional	string	RFC 3339 date-time; return only servers updated at or after it.
search	query	optional	string (1-100)	Case-insensitive substring match on the server name.
version	query	optional	string (1-100)	Accepted for registry compatibility (use "latest"); only the latest version is stored, so any value returns latest.

curl "https://api.agentage.io/api/mcp/v0.1/servers?limit=50"

GET/autocomplete

Anchored-prefix, popularity-ranked typeahead over server names.

Param	In		Type	Description
q	query	required	string (1-100)	Search query, 1-100 chars (trimmed).
limit	query	optional	integer (1-20)	Max suggestions (1-20).

curl "https://api.agentage.io/api/mcp/autocomplete?q=weat&limit=8"

GET/search

Relevance-ranked search over the catalog. sort is ignored (textScore wins).

Param	In		Type	Description
q	query	required	string (1-100)	Search query, 1-100 chars (trimmed).
page	query	optional	integer	Page number, 1-based.
limit	query	optional	integer (1-100)	Items per page (1-100).
type	query	optional	array	Filter by package registry type; "remote" means the server has a hosted endpoint. An unknown value is a 400.
category	query	optional	array	Filter by AI-taxonomy label, exactly as listed by /api/categories. An unknown value is a 400 naming that endpoint.
language	query	optional	array	Filter by GitHub language (exact; an unknown value matches nothing, not a 400).
license	query	optional	array	Filter by GitHub license name ("MIT License") or SPDX id ("MIT"); an unknown value matches nothing, not a 400.
view	query	optional	full \| card

curl "https://api.agentage.io/api/mcp/search?q=weather&type=npm&limit=10"

GET/categories

Each AI-taxonomy label with its server count, most-used first.

curl "https://api.agentage.io/api/mcp/categories"

GET/facets

Categories, languages, and licenses in one call.

curl "https://api.agentage.io/api/mcp/facets"

GET/languages

Each GitHub language with its server count, most-used first.

curl "https://api.agentage.io/api/mcp/languages"

GET/licenses

Each GitHub license with its server count, most-used first.

curl "https://api.agentage.io/api/mcp/licenses"

GET/slugs

Every slug with a lastmod, unpaginated. Feeds the sitemap.

curl "https://api.agentage.io/api/mcp/slugs"

GET/favoritesAuth: Bearer

The signed-in user pinned servers, most-recently-added first.

curl -H "Authorization: Bearer $TOKEN" "https://api.agentage.io/api/mcp/favorites"

POST/favoritesAuth: Bearer

Pin a server by slug. Idempotent; an unknown slug is a 404.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"slug":"example-server"}' "https://api.agentage.io/api/mcp/favorites"

DELETE/favorites/{slug}Auth: Bearer

Unpin a server by slug. Idempotent; a missing favorite still succeeds.

Param	In		Type	Description
slug	path	required	string (1-200)	Catalog server slug.

curl -X DELETE -H "Authorization: Bearer $TOKEN" "https://api.agentage.io/api/mcp/favorites/example-server"

GET/openapi.json

The machine-readable OpenAPI 3.1 spec for this API.

curl "https://api.agentage.io/api/mcp/openapi.json"

Response envelope

// success
{ "success": true, "data": <payload>, "meta": <optional> }

// failure
{ "success": false, "error": { "code": "STRING_CODE", "message": "..." } }

error.code is always a stable constant (INVALID_QUERY, NOT_FOUND, METHOD_NOT_ALLOWED, UNAUTHORIZED, RATE_LIMITED, INTERNAL_ERROR). meta.pagination is present on list and search.

Rate limits, CORS, and stability

Rate limited with a lift: 30 req/s (burst 60) anonymous, keyed by IP; a valid agentage bearer lifts you to 100 req/s (burst 200), keyed by user. Every response carries X-RateLimit-*; over the limit returns 429 with Retry-After.
CORS is open - any origin may read the API directly from the browser.
GET-only except /favorites; any other verb returns 405 with an Allow: GET header.
Read-only and additive-only: fields and endpoints are added, never removed or renamed under this contract. The { success, data, meta } envelope is invariant.