> ## 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.

# Listings

> Manage your Hub listing visibility, metadata, and tier

## Overview

Every MCP server deployed on ezForge Platform or Ready **on a paid plan** automatically gets a **Basic listing** on Hub — no action required. Upgrade to Featured or Premium for enhanced visibility and analytics.

## Listing anatomy

Each Hub listing includes:

* **Server metadata** — Name, description, version, endpoint URL
* **SKILL.md** — Auto-generated capability manifest (see [SKILL.md](/hub/skill-md))
* **Capability document** — Optional SKILL.md or JSON file uploaded by the owner to describe MCP tools in structured form; discoverable via [`GET /.well-known/mcp-skills`](/hub/api-reference#skills-discovery-registry)
* **Verification tier** — Trust badge based on publisher verification level
* **Health score** — Real-time uptime and response-time score (0–100)
* **Agent analytics** — Discovery and interaction metrics

## Listing tiers

### Basic (\$0/mo)

Auto-created for every Platform and Ready customer on a paid plan. Includes:

* Listed in Hub search results
* Auto-generated SKILL.md
* View count analytics

### Featured (\$29/mo)

Self-serve upgrade for increased visibility:

* **Priority placement** in search results
* Custom description and keywords in SKILL.md
* Views + click-through analytics
* Agent breakdown (which AI platforms discover you)

### Premium (\$79/mo)

Maximum visibility and analytics:

* **Top placement** + featured badge in search results
* Composite skill eligibility (appear in multi-server workflows)
* Full analytics: query patterns, conversion funnel, competitive positioning
* Referral commission tracking

## Verification tiers

Hub displays a verification badge on every listing to help AI agents assess publisher credibility. The four tiers map to the `VerificationLevel` type returned by the Directory API:

| `VerificationLevel` | Badge               | What it signals to agents                                                                 |
| ------------------- | ------------------- | ----------------------------------------------------------------------------------------- |
| `unverified`        | (none)              | Business registered; no identity signals confirmed                                        |
| `phone_verified`    | ✓ Phone Verified    | Business phone number confirmed via SMS — reduces spam listings                           |
| `business_verified` | ✓ Business Verified | Account ≥ 30 days old and phone-verified; Google Business Profile cross-reference in Beta |
| `premium_verified`  | ★ Premium Verified  | Manually reviewed by ezForge team — highest trust signal for agents                       |

Higher verification tiers receive ranking boosts in Hub search results. Agents can filter the [Directory API](/api-reference/directory) by minimum verification level using `min_verification`. See [Business Verification](/ready/verification) for how to advance through tiers.

## Managing your listing

From the Hub dashboard you can:

* Edit your listing description and keywords
* Upload a logo and banner image
* Set your listing category and tags
* View analytics and discovery metrics
* Upgrade or downgrade your listing tier

## Uploading a capability document

Any listing owner can upload a SKILL.md or JSON capability document that describes the MCP server's tools in structured form. Once uploaded, the document is publicly retrievable at `GET /api/v1/hub/listings/:id/capability-doc` and indexed in the Hub-level skills registry at `GET /.well-known/mcp-skills` — allowing agent platforms to discover your server's capabilities directly.

```bash theme={null}
curl -X POST https://ezforge.ai/api/v1/hub/listings/<listing-id>/capability-doc \
  -H "Authorization: Bearer <user-token>" \
  -F "file=@SKILL.md;type=text/markdown"
```

See the [Capability documents API reference](/hub/api-reference#capability-documents) for accepted file formats, size limits, and the full response schema.

## Score Analysis

The **Score Analysis** page gives listing owners a full breakdown of their trust score, health sub-components, and prioritized improvement actions. It is only accessible to the listing owner — visiting `/hub/listings/:id/score` for a listing you do not own redirects you to `/hub/dashboard`.

### Navigating to the page

* From `/hub/dashboard/listings/:id`, click the **Full Analysis** button in the score card.
* Or navigate directly to `/hub/listings/:id/score`.

### Trust score donut chart

The page opens with an SVG donut chart displaying your overall trust score (0–100) in the center. The ring is divided into three sectors sized by their maximum contribution weight:

| Sector               | Weight | Color   |
| -------------------- | ------ | ------- |
| Verification         | 50%    | Indigo  |
| Profile Completeness | 25%    | Amber   |
| Service Health       | 25%    | Emerald |

Each sector is filled from its start angle according to the percentage of points earned in that component. The unfilled portion of each sector appears in a neutral gray. This makes it immediately clear which component is dragging your score down.

### Component scores

Below the chart, three progress bars show the raw point totals for each main component (`current / max pts`). Bar color reflects the earned percentage — green at ≥75%, amber at ≥40%, and red below 40%.

The **Service Health** component expands into a sub-breakdown panel showing three contributing factors:

| Sub-component        | What it measures                                                                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Uptime (30 days)** | Percentage of probes returning `up` over the last 30 days                                                                                              |
| **Latency Score**    | Step-function score from average response latency in the last 24 hours: ≤200 ms → 100%, ≤500 ms → 80%, ≤1000 ms → 60%, ≤3000 ms → 30%, otherwise → 10% |
| **Uptime Streak**    | Consecutive up-probe bonus from the most recent probe: ≥288 probes → 100%, ≥72 → 80%, ≥12 → 60%, >0 → 40%, none → 20%                                  |

Each sub-component bar uses the same emerald/amber/red coloring based on its individual percentage.

### Trust improvement pathways

The **Trust Improvement Pathways** section lists every available action that can raise your trust score, sorted by `pointGain` descending so you always see the highest-impact item first. Each row shows the action label, a description of what it earns, a `+N pts` badge, and a CTA button that links directly to the relevant dashboard page (e.g., the verification flow or the listing edit form).

When your listing has a perfect score, the section displays a success message instead of the action list.

### 30-day uptime sparkline

The **Health Score History** section shows a per-day uptime sparkline for the last 30 calendar days (UTC). Each day is rendered as a colored dot:

| Dot color       | Uptime percentage      |
| --------------- | ---------------------- |
| Emerald (green) | ≥ 80%                  |
| Amber           | 50–79%                 |
| Red             | \< 50%                 |
| Gray            | No probe data that day |

An average uptime summary (across days that have data) appears in the top-right corner. If no health probe data has been recorded yet for the listing, the section shows an empty state noting that results appear once probing starts.

**Note:** The trust score shown on this page is the stored value and is updated asynchronously; it may temporarily differ from the sum of the component point totals while a recalculation is in progress.

***

## API reference

### Score breakdown

Return the trust/health score breakdown for a listing, including per-component point totals and a sorted list of improvement actions:

```
GET /v1/hub/listings/{id}/score
```

**Auth:** Explorer+ Hub API key

**URL parameters:**

| Parameter | Type   | Description         |
| --------- | ------ | ------------------- |
| `id`      | string | ULID of the listing |

**Example request:**

```bash theme={null}
GET /v1/hub/listings/01JQXYZ.../score
Authorization: Bearer hub_key_...
```

**Response (200):**

```json theme={null}
{
  "data": {
    "listingId": "01JQXYZ...",
    "trustScore": 67,
    "healthScore": 88,
    "components": [
      {
        "key": "verification",
        "label": "Verification",
        "description": "Current tier: Business Verified. Higher tiers earn more trust points (50 pts max).",
        "current": 34,
        "max": 50,
        "pct": 67
      },
      {
        "key": "profile",
        "label": "Profile Completeness",
        "description": "Name, description, capabilities, location, and MCP protocol version.",
        "current": 20,
        "max": 25,
        "pct": 80
      },
      {
        "key": "health",
        "label": "Service Health",
        "description": "30-day uptime, response latency, and consecutive uptime streak.",
        "current": 22,
        "max": 25,
        "pct": 88
      }
    ],
    "improvements": [
      {
        "key": "upgrade_tier_4",
        "label": "Upgrade to Premium Verified",
        "description": "Complete Premium Verified verification to earn 16 more trust points.",
        "pointGain": 16,
        "ctaLabel": "Verify now",
        "ctaPath": "/hub/dashboard/listings/01JQXYZ.../verify"
      },
      {
        "key": "complete_profile",
        "label": "Complete your listing profile",
        "description": "Add missing fields to reach 100% completeness and earn 5 more trust points.",
        "pointGain": 5,
        "ctaLabel": "Edit listing",
        "ctaPath": "/hub/dashboard/listings/01JQXYZ.../edit"
      },
      {
        "key": "improve_health",
        "label": "Improve service reliability",
        "description": "Maximize uptime and reduce response latency to earn 3 more trust points.",
        "pointGain": 3,
        "ctaLabel": "View health history",
        "ctaPath": "/hub/dashboard/listings/01JQXYZ.../health"
      }
    ]
  }
}
```

The `improvements` array is empty when the listing has a perfect score. Items are sorted by `pointGain` descending (highest-impact action first). `components` are ordered: verification → profile → health.

**Note:** `trustScore` is the stored value from the database and is updated asynchronously; it may temporarily differ from `sum(components[].current)` while a recalculation is in progress.

**Score component fields:**

| Field         | Type    | Description                                                                                                                                  |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | string  | Component identifier: `verification`, `profile`, or `health`                                                                                 |
| `label`       | string  | Human-readable component name                                                                                                                |
| `description` | string  | Explanation of what the component measures                                                                                                   |
| `current`     | integer | Points this component currently contributes (0–`max`)                                                                                        |
| `max`         | integer | Maximum points this component can contribute                                                                                                 |
| `pct`         | integer | Percentage of maximum earned (0–100). For the verification component, reflects the tier's weight directly rather than `current / max × 100`. |

**Improvement action fields:**

| Field         | Type    | Description                                                                      |
| ------------- | ------- | -------------------------------------------------------------------------------- |
| `key`         | string  | Action identifier (e.g., `upgrade_tier_4`, `complete_profile`, `improve_health`) |
| `label`       | string  | Short action label                                                               |
| `description` | string  | What completing this action earns                                                |
| `pointGain`   | integer | Whole-number trust-score points gained if completed                              |
| `ctaLabel`    | string  | Call-to-action button label                                                      |
| `ctaPath`     | string  | Dashboard path for the action                                                    |

**Error codes:**

| Status | Code               | Condition                                                |
| ------ | ------------------ | -------------------------------------------------------- |
| 400    | `VALIDATION_ERROR` | `id` is not a valid 26-character ULID                    |
| 401    | `unauthorized`     | Missing, malformed, or revoked Hub API key               |
| 404    | `not_found`        | Listing not found or not active                          |
| 429    | `rate_limited`     | IP or API key rate limit exceeded (`Retry-After: 86400`) |
| 503    | —                  | Rate-limit service temporarily unavailable               |