{"openapi":"3.1.0","info":{"title":"MCP Catalog API","version":"1.0.0","description":"Public, read-only HTTP API over the agentage MCP Catalog - a crawled mirror of the\nofficial MCP registry. No key, no signup.\n\nEvery response is the standard envelope: `{ \"success\": true, \"data\": ..., \"meta\": ... }`\non success, `{ \"success\": false, \"error\": { \"code\", \"message\" } }` on failure. `error.code`\nis always a stable constant (INVALID_QUERY, NOT_FOUND, METHOD_NOT_ALLOWED, UNAUTHORIZED,\nAUTH_UNAVAILABLE, RATE_LIMITED, INTERNAL_ERROR).\n\nRate limited per caller with a Docker Hub-style lift: anonymous callers get 30 req/s\n(burst 60), keyed by IP; presenting a valid agentage bearer lifts you to 100 req/s\n(burst 200), keyed by user. A missing/invalid bearer just forfeits the lift, never a 401.\nEvery /api response carries X-RateLimit-Limit/Remaining/Reset; over the limit returns 429\nRATE_LIMITED with Retry-After. CORS is open. GET-only except /favorites; any other verb\nreturns 405 with an Allow: GET header. Read-only and additive-only - fields and endpoints\nare added, never removed or renamed under this contract. Only /favorites is authenticated\n(bearer) and writable.","license":{"name":"MIT","identifier":"MIT"},"contact":{"name":"agentage","url":"https://agentage.io"}},"servers":[{"url":"https://api.agentage.io/api/mcp","description":"Public suite API host"}],"tags":[{"name":"Catalog","description":"Browse and read catalog servers."},{"name":"Registry","description":"Official-registry-compatible read alias."},{"name":"Search","description":"Full-text search and typeahead."},{"name":"Facets","description":"Browse-facet counts."},{"name":"Sitemap","description":"Bulk slug feed."},{"name":"Favorites","description":"Per-user pinned servers (authenticated)."},{"name":"Meta","description":"API metadata."}],"paths":{"/mcps":{"get":{"operationId":"listServers","summary":"List catalog servers","description":"Paginated, filterable, sortable server list. All filters AND-combine.","tags":["Catalog"],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number, 1-based.","schema":{"default":1,"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"description":"Items per page (1-100).","schema":{"default":24,"type":"integer","minimum":1,"maximum":100}},{"name":"type","in":"query","required":false,"description":"Filter by package registry type; \"remote\" means the server has a hosted endpoint.","schema":{"type":"string","enum":["npm","pypi","oci","mcpb","nuget","remote"]}},{"name":"category","in":"query","required":false,"description":"Filter by AI-taxonomy label (exact match).","schema":{"type":"string","enum":["Development & Coding","Data & Databases","Search & Web","AI & Machine Learning","Productivity & Docs","Communication & Messaging","Cloud & DevOps","Finance & Crypto","Security","Media & Design","Browser & Automation","Knowledge & Memory","Commerce & Marketing","Other"]}},{"name":"language","in":"query","required":false,"description":"Filter by GitHub language (exact; an unknown value matches nothing, not a 400).","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"license","in":"query","required":false,"description":"Filter by GitHub license (exact; an unknown value matches nothing, not a 400).","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"sort","in":"query","required":false,"description":"Sort order: name asc, stars/updated/downloads desc, with a slug asc tie-break.","schema":{"default":"name","type":"string","enum":["name","stars","updated","downloads"]}}],"responses":{"200":{"description":"A page of servers plus pagination meta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerListResponse"}}}},"400":{"description":"INVALID_QUERY: a query param failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/mcps?type=npm&category=Security&sort=stars&limit=24\""}},"/mcps/{slug}":{"get":{"operationId":"getServer","summary":"Get one server","description":"Single server detail, merging its README and captured tools when present.","tags":["Catalog"],"parameters":[{"name":"slug","in":"path","required":true,"description":"Catalog server slug.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"The server detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerDetailResponse"}}}},"404":{"description":"NOT_FOUND: unknown slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/mcps/example-server\""}},"/v0.1/servers":{"get":{"operationId":"listRegistryServers","summary":"Registry-compatible server list","description":"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.","tags":["Registry"],"parameters":[{"name":"cursor","in":"query","required":false,"description":"Opaque pagination cursor from a prior page metadata.nextCursor; pass it back verbatim.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"description":"Max servers per page (1-100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"updated_since","in":"query","required":false,"description":"RFC 3339 date-time; return only servers updated at or after it.","schema":{"type":"string","format":"date-time"}},{"name":"search","in":"query","required":false,"description":"Case-insensitive substring match on the server name.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"version","in":"query","required":false,"description":"Accepted for registry compatibility (use \"latest\"); only the latest version is stored, so any value returns latest.","schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"A page of servers in the registry envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryListResponse"}}}},"400":{"description":"INVALID_QUERY: a bad limit/updated_since/cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/v0.1/servers?limit=50\""}},"/search":{"get":{"operationId":"searchServers","summary":"Full-text search","description":"Relevance-ranked search over the catalog. sort is ignored (textScore wins).","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query, 1-100 chars (trimmed).","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"page","in":"query","required":false,"description":"Page number, 1-based.","schema":{"default":1,"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"description":"Items per page (1-100).","schema":{"default":24,"type":"integer","minimum":1,"maximum":100}},{"name":"type","in":"query","required":false,"description":"Filter by package registry type; \"remote\" means the server has a hosted endpoint.","schema":{"type":"string","enum":["npm","pypi","oci","mcpb","nuget","remote"]}},{"name":"category","in":"query","required":false,"description":"Filter by AI-taxonomy label (exact match).","schema":{"type":"string","enum":["Development & Coding","Data & Databases","Search & Web","AI & Machine Learning","Productivity & Docs","Communication & Messaging","Cloud & DevOps","Finance & Crypto","Security","Media & Design","Browser & Automation","Knowledge & Memory","Commerce & Marketing","Other"]}},{"name":"language","in":"query","required":false,"description":"Filter by GitHub language (exact; an unknown value matches nothing, not a 400).","schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"license","in":"query","required":false,"description":"Filter by GitHub license (exact; an unknown value matches nothing, not a 400).","schema":{"type":"string","minLength":1,"maxLength":80}}],"responses":{"200":{"description":"Matching servers plus pagination and the echoed query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"INVALID_QUERY: missing/empty q or a bad shared param.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/search?q=weather&type=npm&limit=10\""}},"/autocomplete":{"get":{"operationId":"autocomplete","summary":"Typeahead suggestions","description":"Anchored-prefix, popularity-ranked typeahead over server names.","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query, 1-100 chars (trimmed).","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"limit","in":"query","required":false,"description":"Max suggestions (1-20).","schema":{"type":"integer","minimum":1,"maximum":20,"default":8}}],"responses":{"200":{"description":"A lean list of prefix matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutocompleteResponse"}}}},"400":{"description":"INVALID_QUERY: missing/empty q or out-of-range limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/autocomplete?q=weat&limit=8\""}},"/categories":{"get":{"operationId":"listCategories","summary":"Category facet counts","description":"Each AI-taxonomy label with its server count, most-used first.","tags":["Facets"],"responses":{"200":{"description":"Category counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryCountsResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/categories\""}},"/languages":{"get":{"operationId":"listLanguages","summary":"Language facet counts","description":"Each GitHub language with its server count, most-used first.","tags":["Facets"],"responses":{"200":{"description":"Language counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetCountsResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/languages\""}},"/licenses":{"get":{"operationId":"listLicenses","summary":"License facet counts","description":"Each GitHub license with its server count, most-used first.","tags":["Facets"],"responses":{"200":{"description":"License counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetCountsResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/licenses\""}},"/facets":{"get":{"operationId":"listFacets","summary":"All facet counts","description":"Categories, languages, and licenses in one call.","tags":["Facets"],"responses":{"200":{"description":"All three facet lists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FacetsResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/facets\""}},"/slugs":{"get":{"operationId":"listSlugs","summary":"Slug feed","description":"Every slug with a lastmod, unpaginated. Feeds the sitemap.","tags":["Sitemap"],"responses":{"200":{"description":"Every slug plus its lastmod.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlugsResponse"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/slugs\""}},"/favorites":{"get":{"operationId":"listFavorites","summary":"List favorites","description":"The signed-in user pinned servers, most-recently-added first.","tags":["Favorites"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The user favorites.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FavoritesListResponse"}}}},"401":{"description":"UNAUTHORIZED: missing or invalid bearer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"AUTH_UNAVAILABLE: auth service unreachable - retry, do not sign out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl -H \"Authorization: Bearer $TOKEN\" \"https://api.agentage.io/api/mcp/favorites\""},"post":{"operationId":"addFavorite","summary":"Add a favorite","description":"Pin a server by slug. Idempotent; an unknown slug is a 404.","tags":["Favorites"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","minLength":1,"maxLength":200}}}}}},"responses":{"200":{"description":"The pinned slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlugAckResponse"}}}},"401":{"description":"UNAUTHORIZED: missing or invalid bearer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NOT_FOUND: unknown slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"AUTH_UNAVAILABLE: auth service unreachable - retry, do not sign out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl -X POST -H \"Authorization: Bearer $TOKEN\" -H \"Content-Type: application/json\" -d '{\"slug\":\"example-server\"}' \"https://api.agentage.io/api/mcp/favorites\""}},"/favorites/{slug}":{"delete":{"operationId":"removeFavorite","summary":"Remove a favorite","description":"Unpin a server by slug. Idempotent; a missing favorite still succeeds.","tags":["Favorites"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"description":"Catalog server slug.","schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"The unpinned slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlugAckResponse"}}}},"401":{"description":"UNAUTHORIZED: missing or invalid bearer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"AUTH_UNAVAILABLE: auth service unreachable - retry, do not sign out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-curl":"curl -X DELETE -H \"Authorization: Bearer $TOKEN\" \"https://api.agentage.io/api/mcp/favorites/example-server\""}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This OpenAPI document","description":"The machine-readable OpenAPI 3.1 spec for this API.","tags":["Meta"],"responses":{"200":{"description":"The OpenAPI document.","content":{"application/json":{"schema":{"type":"object"}}}}},"x-curl":"curl \"https://api.agentage.io/api/mcp/openapi.json\""}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A session JWT or an opaque OAuth access token minted by the agentage auth server."}},"schemas":{"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable error-code constant.","example":"INVALID_QUERY"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}},"Pagination":{"type":"object","required":["page","limit","total","totalPages","hasMore"],"properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"},"hasMore":{"type":"boolean"}}},"CatalogPackage":{"type":"object","required":["registryType","identifier"],"properties":{"registryType":{"type":"string","example":"npm"},"identifier":{"type":"string"},"version":{"type":"string"}}},"CatalogRemote":{"type":"object","required":["type","url"],"properties":{"type":{"type":"string","example":"streamable-http"},"url":{"type":"string","format":"uri"}}},"CatalogGithub":{"type":"object","properties":{"language":{"type":"string"},"license":{"type":"string"},"stars":{"type":"integer"}}},"CatalogTool":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","additionalProperties":true}}},"ReadmeContent":{"type":"object","required":["content","path","size","sha"],"properties":{"content":{"type":"string"},"path":{"type":"string"},"size":{"type":"integer"},"sha":{"type":"string"}}},"CatalogServer":{"type":"object","required":["slug","name","description","version","status","isOfficial","crawledAt","packages","remotes"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string","example":"active"},"repositoryUrl":{"type":"string","format":"uri"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPackage"}},"remotes":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRemote"}},"isOfficial":{"type":"boolean"},"crawledAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"category":{"type":"array","items":{"type":"string"}},"github":{"$ref":"#/components/schemas/CatalogGithub"},"toolCount":{"type":"integer"}}},"CatalogServerDetail":{"allOf":[{"$ref":"#/components/schemas/CatalogServer"},{"type":"object","properties":{"readme":{"$ref":"#/components/schemas/ReadmeContent"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/CatalogTool"}}}}]},"CategoryCount":{"type":"object","required":["name","count"],"properties":{"name":{"type":"string"},"count":{"type":"integer"}}},"FacetCount":{"type":"object","required":["name","count"],"properties":{"name":{"type":"string"},"count":{"type":"integer"}}},"FacetsData":{"type":"object","required":["categories","languages","licenses"],"properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryCount"}},"languages":{"type":"array","items":{"$ref":"#/components/schemas/FacetCount"}},"licenses":{"type":"array","items":{"$ref":"#/components/schemas/FacetCount"}}}},"SlugEntry":{"type":"object","required":["slug","updatedAt"],"properties":{"slug":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}},"AutocompleteItem":{"type":"object","required":["slug","name","title","description"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"}}},"CatalogHealth":{"type":"object","required":["live","checkedAt"],"properties":{"live":{"type":"boolean"},"authRequired":{"type":"boolean"},"toolCount":{"type":"integer"},"checkedAt":{"type":"string","format":"date-time"}}},"RegistryServerRecord":{"type":"object","required":["name","description","version","status","packages","remotes"],"description":"The retained subset of the upstream server.json record (reconstructed, not byte-exact).","properties":{"name":{"type":"string","example":"io.github.owner/example"},"title":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"status":{"type":"string","example":"active"},"repository":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"source":{"type":"string","example":"github"},"subfolder":{"type":"string"}}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPackage"}},"remotes":{"type":"array","items":{"$ref":"#/components/schemas/CatalogRemote"}}}},"TrustGrades":{"type":"object","required":["license","maintenance","quality"],"properties":{"license":{"type":"string","enum":["A","B","C","D","F"],"nullable":true},"maintenance":{"type":"string","enum":["A","B","C","D","F"],"nullable":true},"quality":{"type":"string","enum":["untested"]}}},"CatalogMeta":{"type":"object","required":["slug","grades"],"description":"Agentage catalog extension block, keyed under _meta['io.agentage.catalog/v0'].","properties":{"slug":{"type":"string"},"grades":{"$ref":"#/components/schemas/TrustGrades"},"categories":{"type":"array","items":{"type":"string"}},"toolCount":{"type":"integer"},"health":{"$ref":"#/components/schemas/CatalogHealth"},"downloads":{"type":"integer","description":"npm downloads in the last month."},"updatedAt":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri","description":"Our human detail page for this server."}}},"RegistryEntry":{"type":"object","required":["server","_meta"],"properties":{"server":{"$ref":"#/components/schemas/RegistryServerRecord"},"_meta":{"type":"object","required":["io.agentage.catalog/v0"],"properties":{"io.agentage.catalog/v0":{"$ref":"#/components/schemas/CatalogMeta"}},"additionalProperties":true}}},"RegistryMetadata":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","description":"Number of servers in this page."},"nextCursor":{"type":"string","description":"Opaque cursor for the next page; absent on the last page."}}},"ErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"$ref":"#/components/schemas/ApiError"}}},"ServerListResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogServer"}},"meta":{"type":"object","required":["pagination"],"properties":{"pagination":{"$ref":"#/components/schemas/Pagination"}}}}},"ServerDetailResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/CatalogServerDetail"}}},"SearchResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogServer"}},"meta":{"type":"object","required":["pagination","search"],"properties":{"pagination":{"$ref":"#/components/schemas/Pagination"},"search":{"type":"object","required":["query"],"properties":{"query":{"type":"string"}}}}}}},"AutocompleteResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/AutocompleteItem"}}}},"CategoryCountsResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CategoryCount"}}}},"FacetCountsResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/FacetCount"}}}},"FacetsResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/FacetsData"}}},"SlugsResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/SlugEntry"}}}},"RegistryListResponse":{"type":"object","required":["servers","metadata"],"properties":{"servers":{"type":"array","items":{"$ref":"#/components/schemas/RegistryEntry"}},"metadata":{"$ref":"#/components/schemas/RegistryMetadata"}}},"FavoritesListResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogServer"}}}},"SlugAckResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string"}}}}}}}}