Search & Discovery - ezForge AI

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:

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:

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:

curl "https://ezforge.ai/.well-known/mcp-skills?format=skill_md&limit=5"

Example response:

{
  "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 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:

{
  "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 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)

​Overview

​Discovery methods

​Hub Search API

​Directory API

​Well-Known Metadata

​Hub Skills Registry

​Hub MCP Registry

​WebMCP Integration

​Search architecture

​Search ranking

​Composite skills

​API access