> ## Documentation Index > Fetch the complete documentation index at: https://docs.ezforge.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search & Discovery > How AI agents find MCP servers through Hub's discovery API ## Overview Hub provides a search and discovery API that AI agents and agent platforms use to find verified MCP servers matching specific needs. Results are ranked by relevance, verification tier, and health score. ## Discovery methods ### Hub Search API The primary discovery endpoint for AI agents: ```bash theme={null} GET /v1/hub/search?q=restaurant+detroit&vertical=restaurant&city=detroit ``` Returns ranked listings with metadata, SKILL.md summaries, and connection details. ### Directory API Structured browsing by category, location, and capability: ```bash theme={null} GET /v1/hub/directory?vertical=restaurant&city=detroit&capabilities=reservation_booking ``` ### Well-Known Metadata Every MCP server on ezForge exposes a standard discovery endpoint: ``` https://{slug}.mcp.ezforge.ai/.well-known/mcp-server-metadata ``` This returns structured metadata (name, vertical, location, capabilities) that any agent can consume directly. ### Hub Skills Registry The Hub-level skills discovery endpoint enumerates all active listings that have uploaded a capability document (SKILL.md or JSON): ``` GET https://ezforge.ai/.well-known/mcp-skills ``` Unlike `/.well-known/mcp-server-metadata` (which is server-scoped), this endpoint is Hub-scoped — it aggregates capability documents across all participating listings into a single, paginated registry. Agent platforms use it to discover available MCP server skill sets without crawling individual listings. **Example request:** ```bash theme={null} curl "https://ezforge.ai/.well-known/mcp-skills?format=skill_md&limit=5" ``` **Example response:** ```json theme={null} { "listings": [ { "id": "01JQXYZ0000000000000000000", "name": "Detroit Eats MCP", "capability_doc_url": "https://storage.ezforge.ai/hub-bucket/hub/capability-docs/01JQXYZ.../01JQABC....md", "capability_doc_format": "skill_md" } ], "next_cursor": "01JQXYZ0000000000000000000" } ``` Supports `listing_id`, `format` (`skill_md` | `json`), `limit` (1–200, default 50), and `cursor` query parameters for filtering and keyset pagination. Responses are cached for 60 seconds. See the [full API reference](/hub/api-reference#skills-discovery-registry) for the complete parameter and error documentation. ### Hub MCP Registry The Hub exposes a machine-readable registry document describing the Hub's overall capabilities and API surface: ``` GET https://ezforge.ai/.well-known/mcp-registry.json ``` Public — no authentication required. Agent platforms use this document to learn about the Hub as a whole (discovery URLs, supported capabilities, authentication requirements) without querying individual listings. **Example response:** ```json theme={null} { "id": "ezforge-hub", "name": "ezForge Hub", "description": "The ezForge Hub is a verified registry of AI-ready business services. AI agents use the Hub to discover, trust-check, and connect to MCP-compatible business services.", "url": "https://hub.ezforge.ai", "mcp_version": "2025-11-25", "registry_version": "0.1", "capabilities": [ "discovery", "search", "composites", "skill_md", "verification", "health_monitoring" ], "discovery_api": "https://hub.ezforge.ai/api/v1/hub/search", "skill_md_endpoint": "https://hub.ezforge.ai/api/v1/hub/listings/{listing_id}/skill.md", "composites_endpoint": "https://hub.ezforge.ai/api/v1/hub/composites", "auth": { "required": true, "type": "hub_api_key", "docs_url": "https://hub.ezforge.ai/docs/authentication" }, "contact": { "url": "https://hub.ezforge.ai/contact" } } ``` **Response fields:** | Field | Type | Description | | --------------------- | --------- | ------------------------------------------------------------------------------------------------------ | | `id` | string | Registry identifier (always `"ezforge-hub"`) | | `name` | string | Human-readable Hub name | | `description` | string | Hub description | | `url` | string | Hub base URL | | `mcp_version` | string | MCP spec revision this Hub implementation targets (currently `"2025-11-25"`) | | `registry_version` | string | Registry document schema version | | `capabilities` | string\[] | Hub capabilities: `discovery`, `search`, `composites`, `skill_md`, `verification`, `health_monitoring` | | `discovery_api` | string | Base URL for Hub search/discovery queries | | `skill_md_endpoint` | string | URL template for per-listing SKILL.md retrieval (replace `{listing_id}` with the listing ULID) | | `composites_endpoint` | string | Base URL for composite skill queries | | `auth.required` | boolean | Whether Hub discovery APIs require authentication | | `auth.type` | string | Auth scheme (currently `"hub_api_key"`) | | `auth.docs_url` | string | URL for authentication documentation | | `contact.url` | string | Hub contact page URL | ### WebMCP Integration For businesses with existing websites, Ready auto-generates a WebMCP metadata tag. Agents crawling the web discover the MCP endpoint from the business's existing site. ## Search architecture Hub search is powered by a **Typesense** read-replica index derived from PostgreSQL (the source of truth). This architecture provides: * **Typo-tolerant full-text search** across business names, descriptions, and capabilities * **Faceted filtering** by vertical, location, capabilities, and verification tier * **Geospatial queries** — find services within a radius of a lat/lng coordinate * **Sub-50ms query latency** at scale PostgreSQL GIN indexes are retained for internal/admin queries. The Typesense index is synced from PostgreSQL via change-data-capture (CDC) or periodic refresh. ## Search ranking Hub ranks search results using a composite score: | Signal | Weight | Description | | --------------------- | ------ | -------------------------------------------- | | **Relevance** | High | Text match against query, vertical, location | | **Verification tier** | Medium | Higher verification = higher rank | | **Health score** | Medium | Uptime and response-time metrics | | **Listing tier** | Medium | Premium > Featured > Basic | | **Agent engagement** | Low | Historical interaction success rate | ## Composite skills **Composite skills** aggregate capabilities from multiple MCP servers into a single discoverable unit. Any verified listing (Tier 2+) can participate — composite eligibility is not restricted to Premium listings. Composites are discoverable through three channels: * **Browse API** — `GET /v1/hub/composites/browse` returns the public catalog of system-generated and user-promoted composites, paginated and ranked by trust * **Composite SKILL.md** — `GET /v1/hub/composites/{id}/skill.md` returns a portable capability manifest for a specific composite * **`hub_browse_composites` MCP tool** — agents consuming Hub natively can call this tool to browse the public composite catalog without constructing HTTP requests See the [Composite Skills](/hub/composites) page for full API documentation, trust rules, and the `created_by` lifecycle model. ## API access Hub's discovery API is available to: | Consumer | Access | | ----------------------------------- | --------------------------------------------- | | AI agents (Claude, ChatGPT, etc.) | Free — standard rate limits | | Agent platforms (Anthropic, OpenAI) | API key + higher rate limits | | Third-party registries | Partnership agreements | | Developers | API key (included with Platform subscription) |