MCP Server List

API documentation

REST and MCP share the same profiles, eligibility reports, payments and submission results. Payment starts the approved jobs.

OpenAPI specificationAgent quickstart

Authentication

POST /api/v1/accounts accepts a workspace name and optional contact email. Save the once-returned data.api_key privately. Anonymous signup creates a fresh account; email and anonymous idempotency keys do not retrieve another account.

Use X-API-Key or Bearer API keys for protected calls. MPP requires X-API-Key because Authorization carries the Payment credential. Browser sessions are HttpOnly and SameSite=Strict; cookie mutations must be same-origin.

Base URL: https://mcpserverlist.io/api/v1

Connect owner credentials privately

POST /connections accepts provider, secret and optional expires_at. Supported providers are GitHub, registry and Smithery. Send the body directly over HTTPS from the owner’s secrets store. Never include provider secrets in MCP arguments, chat, public manifests or logs.

The response contains metadata and an opaque connection ID. Use IDs in connection_refs; GET /connections returns metadata only and DELETE /connections/:id revokes an owned credential. Connections are encrypted, expiring and tenant-bound.

Supported GitHub registry namespaces use a fresh JWT exchanged from the connected source-owner GitHub identity at execution. Upstream PRs and intake comments use the operator’s separately verified contribution account; Glama reads use the operator’s API credential. Owner source access does not confer upstream contribution rights.

Free checks, then explicit authorization

  1. Discover GET /directories. An anonymous POST /checks gives general repository diagnostics.
  2. Save a profile with POST /servers: repository URL, name, description and transport, plus the package or endpoint and destination fields you actually support. Declare remote access and authentication accurately.
  3. Run POST /preflights with server_id, directory_slugs and opaque connection_refs. Static requirements are checked before charging; external evaluation dependencies are disclosed explicitly.
  4. Read the immutable report: global checks, target states, exact public plans, evidence, blockers and remedies. Resolve all blocked or unavailable targets. Inspect the quote: at least one qualifying new submission is required, excluding passive ingestion and already-listed targets. Disclosed dependencies stay within the same purchase; a worker must support the full set.
  5. After the owner reviews and authorizes the displayed submissions, POST /launches with preflight_id, authorized_amount equal to the saved quote amount, authorize_submissions: true and a stable operation key creates an unpaid draft.

Initial reports expire within 30 minutes. A changed profile, expired connection, paused route or stale report requires fresh checks before a new purchase. For repository fixes, POST /preparations with server_id and github_connection, inspect the patch, then explicitly approve its digest at POST /preparations/:id/pull-request. Preparation never merges changes or publishes a package.

Check the set, authorize an unpaid draft
# After saving your profile and securely connecting the owner:
curl -X POST 'https://mcpserverlist.io/api/v1/preflights' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "server_id":"SERVER_ID",
    "directory_slugs":["official-mcp-registry","cline-marketplace","kilo-marketplace"],
    "connection_refs":{"github":"CONNECTION_ID"}
  }'

# Review every finding and public payload with the owner first.
curl -X POST 'https://mcpserverlist.io/api/v1/launches' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: YOUR_UNIQUE_LAUNCH_KEY' \
  -d '{"preflight_id":"APPROVED_PREFLIGHT_ID",
       "authorized_amount":4900,
       "authorize_submissions":true}'

Pay only the bound eligible launch

POST /billing/pay and POST /billing/checkout require exactly {"launch_id":"APPROVED_LAUNCH_ID"}, account authentication and a purchase Idempotency-Key. New launches cost $49 USD. The preflight freezes its amount, currency and fulfillment window; authorization must match that saved amount. Existing approved launches retain their original price. Caller-supplied prices, coverage overrides and unbound purchases are rejected.

MPP returns an actual HTTP402 Payment challenge. An authorized Stripe SPT wallet retries the identical endpoint/body with the same X-API-Key and Idempotency-Key plus its Payment credential. A verified response includes a receipt and the automatically queued launch.

Checkout returns a human payment URL. A signed paid webhook queues the same authorized job set; visiting the return page does not fulfill it. Late verified settlement still queues its already-bound launch if the preflight expires during payment processing.

On uncertain outcomes, query GET /billing/orders/:id and GET /launches/:id. Preserve the original key and body. Never start another purchase while the first outcome is unknown.

Safe retries and durable execution

Draft authorization and payment require an Idempotency-Key of 8–128 visible ASCII characters. Reuse it only for the same operation and input. One immutable order is bound to one launch; successful retries do not create another charge or job set.

The worker rechecks before its first external write, records provider references and follows supported statuses. An uncertain provider write is reconciled before any resubmission. The customer does not call a separate per-job submission endpoint.

Errors and limits

Errors include error.code, error.message, optional details, retryable and a request ID. Preflight findings explain the specific blocker and remedy.

  • 401 / 403: account, owner or origin authorization failed.
  • 402: the eligible launch’s MPP payment challenge.
  • 409: stale readiness, changed profile, expired connection or conflicting purchase state.
  • 413 / 415 / 422: body size, content type or field validation failure.
  • 429: rate limit; honor the returned retry guidance.
  • 502 / 503: provider failure or unavailable billing, credentials, worker or operator integration.

JSON bodies are limited to 64 KiB. Repository diagnostics use restricted GitHub API reads. Full remote preflight uses bounded public-HTTPS and MCP checks with network safeguards. No tool call is executed merely to demonstrate readiness.

Supported paths depend on prerequisites

The service implements official registry publication, public remote Smithery releases, MCP.so’s maintainer-run intake, checked local and remote awesome-list PRs, validated Docker remote catalog PRs, and Cline/Kilo marketplace PRs for supported npm and public unauthenticated HTTP profiles. Glama uses official-registry ingestion with authenticated discovery verification.

Smithery stdio or authenticated scanning is outside the initial adapter. Awesome-list contributions require real Glama evaluation and the correct local/remote scope; a selected Glama prerequisite can provide that evaluation later in the same launch, before the downstream write. Docker needs the operator’s official validator and approved revision. A browser-based target is purchasable only when its verified workflow is configured; paused PulseMCP intake and standalone-server-to-Cursor-plugin assumptions are excluded.

Assigned service reviews

Stalled jobs create assigned cases with due dates, customer updates and recorded remedies. Read GET /service-cases?limit=25&offset=0; follow page.next_offset to retrieve older reviews. Reply through POST /service-cases/:id/replies. Preparation PRs also track owner merge and release actions. Case resolution cannot mark a provider listing successful.

For an expired connection, upload a fresh credential privately, then call POST /launches/:id/connection with its provider and connection ID. Ownership is checked again; coverage and uncertain-write guards stay intact.

Execution states mean what they say

queued waits for execution; running holds an active worker claim. submitted records an accepted provider action such as a PR, release or intake request. awaiting_ingestion waits for downstream discovery.

listed requires matching provider evidence. needs_attention preserves unresolved prerequisites or uncertain outcomes; failed reports a confirmed unsuccessful action. Mixed results stay visible. A generated URL, issue comment or open PR does not establish directory approval.

Follow supported provider checks and evidence in the saved launch for 90 days from payment. Prerequisite failure or expiration is escalated visibly; unresolved work is never presented as a listing. Indefinite uptime monitoring, automatic future-release synchronization and third-party paid placement are not included in the service fee.

Machine-readable entry points

OpenAPI · Agent manifest · Full agent instructions · Installable skill