premium_agents_directory
Browse and filter an enriched AI agents catalog with live operational status, recent news, traffic data, pricing, and trending scores. Sort by trending, price, or news count. Costs 1 credit.
Instructions
Enriched AI agents catalog joined with live status, recent news, agent traffic, flagship pricing, and a 0-100 trending_score. Costs 1 credit.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | coding, research, general, creative, frameworks | |
| status | No | ||
| open_source | No | ||
| sort | No | ||
| limit | No |
Implementation Reference
- mcp-server/src/index.ts:476-527 (handler)The MCP server tool registration and handler for 'premium_agents_directory'. Defines the tool with Zod schema for inputs (category, status, open_source, sort, limit), builds query params, calls fetchJSON to GET /premium/agents/directory, and formats the response as text content.
// ── Tool: premium_agents_directory (1 credit) ─────────────────────── server.tool( 'premium_agents_directory', 'Enriched AI agents catalog joined with live status, recent news, agent traffic, flagship pricing, and a 0-100 trending_score. Costs 1 credit.', { category: z.string().optional().describe('coding, research, general, creative, frameworks'), status: z.enum(['operational', 'degraded', 'down', 'unknown']).optional(), open_source: z.boolean().optional(), sort: z.enum(['trending', 'alphabetical', 'status', 'price_low', 'price_high', 'news_count']).optional(), limit: z.number().min(1).max(100).optional(), }, async ({ category, status, open_source, sort, limit }) => { const params = new URLSearchParams(); if (category) params.set('category', category); if (status) params.set('status', status); if (typeof open_source === 'boolean') params.set('open_source', String(open_source)); if (sort) params.set('sort', sort); if (typeof limit === 'number') params.set('limit', String(limit)); const data = (await fetchJSON(`/premium/agents/directory?${params}`, { auth: true })) as { total: number; returned: number; sort: string; agents: { id: string; name: string; provider: string; category: string; live_status: string; recent_news_count: number; flagship_pricing: { model: string; blended: number } | null; trending_score: number; }[]; billing?: { credits_remaining?: number }; }; const list = data.agents .map( a => ` ${a.name} (${a.provider}) [${a.category}] status=${a.live_status} score=${a.trending_score} news=${a.recent_news_count}` + (a.flagship_pricing ? ` flagship=${a.flagship_pricing.model} $${a.flagship_pricing.blended}/1M` : ''), ) .join('\n'); return { content: [ { type: 'text' as const, text: `Agents (sort: ${data.sort}, ${data.returned} of ${data.total}):\n\n${list}\n\nCredits remaining: ${data.billing?.credits_remaining ?? '?'}`, }, ], }; }, ); - mcp-server/src/index.ts:476-527 (registration)Tool registered via server.tool('premium_agents_directory', ...) on the McpServer instance. This is the registration point that makes the tool available in the MCP protocol.
// ── Tool: premium_agents_directory (1 credit) ─────────────────────── server.tool( 'premium_agents_directory', 'Enriched AI agents catalog joined with live status, recent news, agent traffic, flagship pricing, and a 0-100 trending_score. Costs 1 credit.', { category: z.string().optional().describe('coding, research, general, creative, frameworks'), status: z.enum(['operational', 'degraded', 'down', 'unknown']).optional(), open_source: z.boolean().optional(), sort: z.enum(['trending', 'alphabetical', 'status', 'price_low', 'price_high', 'news_count']).optional(), limit: z.number().min(1).max(100).optional(), }, async ({ category, status, open_source, sort, limit }) => { const params = new URLSearchParams(); if (category) params.set('category', category); if (status) params.set('status', status); if (typeof open_source === 'boolean') params.set('open_source', String(open_source)); if (sort) params.set('sort', sort); if (typeof limit === 'number') params.set('limit', String(limit)); const data = (await fetchJSON(`/premium/agents/directory?${params}`, { auth: true })) as { total: number; returned: number; sort: string; agents: { id: string; name: string; provider: string; category: string; live_status: string; recent_news_count: number; flagship_pricing: { model: string; blended: number } | null; trending_score: number; }[]; billing?: { credits_remaining?: number }; }; const list = data.agents .map( a => ` ${a.name} (${a.provider}) [${a.category}] status=${a.live_status} score=${a.trending_score} news=${a.recent_news_count}` + (a.flagship_pricing ? ` flagship=${a.flagship_pricing.model} $${a.flagship_pricing.blended}/1M` : ''), ) .join('\n'); return { content: [ { type: 'text' as const, text: `Agents (sort: ${data.sort}, ${data.returned} of ${data.total}):\n\n${list}\n\nCredits remaining: ${data.billing?.credits_remaining ?? '?'}`, }, ], }; }, ); - sdk/javascript/src/index.ts:359-377 (schema)TypeScript type definitions for the API response types: EnrichedAgentRecord, AgentsDirectorySort, and PremiumAgentsDirectoryResponse. Defines the shape of the enriched agent records with fields like live_status, flagship_pricing, trending_score, etc.
export interface EnrichedAgentRecord { id: string; name: string; provider: string; category: string; description: string; url: string; pricing?: string; launched?: number | string; capabilities?: string[]; openSource?: boolean; live_status: 'operational' | 'degraded' | 'down' | 'unknown'; status_page_url: string | null; recent_news_count: number; recent_news: { title: string; url: string; published_at: string; source: string }[]; agent_traffic_24h: number; flagship_pricing: { model: string; input: number; output: number; blended: number } | null; trending_score: number; } - JavaScript SDK client method premiumAgentsDirectory(). Wraps the GET /premium/agents/directory endpoint with parameter building and token requirement. Provides typed access to the premium agents directory API.
async premiumAgentsDirectory(options?: { category?: string; status?: 'operational' | 'degraded' | 'down' | 'unknown'; openSource?: boolean; capability?: string; sort?: AgentsDirectorySort; limit?: number; }): Promise<PremiumAgentsDirectoryResponse> { this.requireToken('premiumAgentsDirectory'); const params: Record<string, unknown> = { category: options?.category, status: options?.status, capability: options?.capability, sort: options?.sort, limit: options?.limit, }; if (options?.openSource === true) params.open_source = 'true'; else if (options?.openSource === false) params.open_source = 'false'; return this.request<PremiumAgentsDirectoryResponse>('GET', '/premium/agents/directory', { params, requireToken: true, }); - Python SDK client method premium_agents_directory(). Wraps the GET /premium/agents/directory endpoint with parameter building and token requirement. Python equivalent of the JS SDK method.
def premium_agents_directory( self, *, category: str | None = None, status: str | None = None, open_source: bool | None = None, capability: str | None = None, sort: str | None = None, limit: int | None = None, ) -> dict[str, Any]: """Enriched agents directory: catalog joined with live signals. Costs 1 credit per call. Each agent record includes ``live_status``, ``status_page_url``, ``recent_news_count``, ``recent_news`` (top 3), ``agent_traffic_24h``, ``flagship_pricing`` (with blended $/1M), and a derived ``trending_score`` (0-100). Args: category: Filter to one category id (e.g. "coding", "research", "general", "creative", "frameworks"). status: Filter to one live status: "operational", "degraded", "down", or "unknown". open_source: True for OSS-only, False for closed-only. capability: Substring match against an agent's capabilities tags. sort: One of "trending" (default), "alphabetical", "status", "price_low", "price_high", "news_count". limit: Max records to return (1-100, default 50). Returns: Dict with ``agents`` (list), ``total``, ``returned``, ``filters_applied``, ``sort``, ``data_freshness``, and ``billing``. Raises: ValueError: if no token is set on the client PaymentRequired: if the token has insufficient credits """ self._require_token("premium_agents_directory") params: dict[str, Any] = {} if category is not None: params["category"] = category if status is not None: params["status"] = status if open_source is True: params["open_source"] = "true" elif open_source is False: params["open_source"] = "false" if capability is not None: params["capability"] = capability if sort is not None: params["sort"] = sort if limit is not None: params["limit"] = limit return self._request( "GET", "/premium/agents/directory", params=params, require_token=True, )