API reference

Base URLs

Two host families serve the API. The exact origins are configurable per environment — in production they are:

REST responses are JSON. Successful reads return { "data": … } and errors return { "error": { "code", "message" } }. Every response echoes an x-request-id header.

Authentication

Public read endpoints under /api are open — no key required — but they are anonymously rate limited per IP (see Rate limits). Authenticated routes (/api/me…, /api/developer…, /api/admin…) and every gateway call require an API key.

Create a key in your dashboard at /app/keys. A key looks like mcpstore_live_… and is shown once at creation — we store only a hash and a short prefix, so copy it immediately. Present it as a bearer token:

Authorization: Bearer mcpstore_live_xxxxxxxxxxxxxxxxxxxxxxxx

The gateway also accepts the key in an X-MCPStore-Key header as an alternative to Authorization. Treat keys as secrets: never embed them in client-side code or commit them to source control.

Public REST endpoints

All paths below are relative to the REST base URL and accept GET only.

curl https://api.mcpstore.io/api/mcps?category=Databases

curl "https://api.mcpstore.io/api/mcps?q=postgres&pricing=free&verified=1&sort=popular"

curl "https://api.mcpstore.io/api/search?q=github"

curl https://api.mcpstore.io/api/mcps/acme/postgres

Developer API (authenticated)

Manage your listings programmatically with an API key — the same surface as the developer portal. All paths are relative to the REST base URL, take a bearer token, and return { "data": … } (or the standard error shape). Bodies are JSON. Writes are owner-scoped to the key’s account.

A listing body looks like:

curl -X POST https://api.mcpstore.io/api/developer/mcps \
  -H "Authorization: Bearer mcpstore_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub MCP",
    "slug": "github-mcp",
    "shortDescription": "Read and write GitHub from your agent.",
    "category": "Developer Tools",
    "supportedClients": ["claude", "cursor"],
    "endpointUrl": "https://mcp.example.com/github",
    "pricingType": "subscription",
    "riskLabels": ["read_only", "network_access"],
    "plan": { "name": "Pro", "priceCents": 900, "billingInterval": "month", "features": ["unlimited"] }
  }'

Endpoints must be https:// (gateway rule). Only self-declarable capability labels are accepted on riskLabels; trust labels (e.g. publisher_verified) are assigned by MCP Store and ignored here.

Webhooks

Register HTTPS endpoints to receive a signed POST when your listings or payouts change. Manage them in the portal at /app/developer/webhooks or via the API:

Event types: listing.published, listing.submitted, listing.suspended, subscription.updated, payout.updated. Each delivery is JSON { id, type, created, data } with headers X-MCPStore-Event and X-MCPStore-Signature: t=<ts>,v1=<hex>.

Verify the signature by computing HMAC-SHA256(secret, `${t}.${rawBody}`) and comparing it to v1 (constant-time). Reject deliveries whose t is too old to prevent replay.

// Node verification example
import crypto from "node:crypto";
function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Admin API (authenticated)

For admin-role keys only — the programmatic surface of the admin console. Every route requires an API key whose account has the admin role (checked per request); non-admins get 403. Moderation actions append to the audit log.

curl -X POST https://api.mcpstore.io/api/admin/mcps/<id>/status \
  -H "Authorization: Bearer mcpstore_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status":"suspended"}'

Rate limits

The public REST API applies an anonymous, per-IP fixed-window limit — by default 60 requests / minute (configurable per environment; /api/health, the Stripe webhook, and authenticated /api/me… / /api/developer… routes are exempt). When you exceed it the API responds 429 with a Retry-After header and { "error": { "code": "RATE_LIMITED" } }. Responses also carry X-RateLimit-Limit and X-RateLimit-Remaining.

The gateway enforces tiered limits per authenticated user: a per-minute burst limit plus a daily call quota (the free tier’s quota, or your subscription plan’s usage limit on paid listings), with a per-IP backstop. The first exhausted window returns 429 with Retry-After; a daily-quota hit is reported distinctly from a burst hit.

Calling an MCP through the gateway

Once you hold an active subscription (or for free listings), call an MCP through the gateway. The path mirrors the listing’s slugs and the key travels as a bearer token. The gateway authenticates the key, authorizes access against the database (subscription, plan, rate limits), forwards to the developer’s registered HTTPS endpoint, and meters the call (metadata only).

# Replace the slugs and the placeholder key with your own.
curl -X POST https://gateway.mcpstore.io/mcp/acme/postgres \
  -H "Authorization: Bearer mcpstore_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Both GET and POST are accepted. Response codes:

Client libraries

Prefer not to hand-roll requests? @mcpstore/sdk is a tiny, dependency-free fetch-based client (Node, Workers, Deno, browser) that wraps every authenticated surface and throws a typed McpStoreApiError on failure. The mcpstore CLI wraps the SDK for the terminal and CI.

import { createMcpStoreClient } from "@mcpstore/sdk";

const mcp = createMcpStoreClient({ apiKey: process.env.MCPSTORE_API_KEY! });
const mine = await mcp.developer.listMcps();
await mcp.developer.setStatus(mine[0].id as string, "active");

# or from the terminal:
#   MCPSTORE_API_KEY=mcpstore_live_… mcpstore mcps list
#   mcpstore mcps create ./listing.json --api-key mcpstore_live_…

Next steps

Browse listings on /explore to find an MCP and its slugs, then mint a key at /app/keys to start calling the gateway.