mcpbay.pro API

Quickstart

1. Open your account → API tokens and create a token. Choose the permissions the task needs — nothing more. Open API tokens
2. Copy the token right away — it is shown only once. Keep it like a password: in a password manager or in your CI secrets.
3. Check it — the API answers which token this is and what it may do:

curl https://api.mcpbay.pro/v1/token \
  -H "Authorization: Bearer $MCPBAY_TOKEN"

Then call any method. For example, the catalog (no token needed) or your servers:

curl "https://api.mcpbay.pro/v1/catalog/servers?q=github&limit=5"

curl https://api.mcpbay.pro/v1/author/servers \
  -H "Authorization: Bearer $MCPBAY_TOKEN"

Authentication

Send the token in the Authorization header of every request. Tokens are not accepted in the request address or in cookies: the API does not use the website sign-in.

Authorization: Bearer mcpb_pat_…

Tokens start with mcpb_pat_. The fixed prefix makes a token that ended up in code or logs easy to find — for example, with a custom pattern in your secret scanner.

Every token has an expiry date — from 7 days to 1 year, you choose it. We email you when a token is created and, for tokens valid longer than two weeks, 7 days before it expires.

A request with an invalid, expired or revoked token gets 401 invalid_token — the same answer in every case, it does not tell which one it was. This also applies to methods that work without a token: send a valid token or none. A request without a token to a method that needs one gets 401 unauthorized.

Do not put tokens into browser code or mobile apps: anyone can extract them from there. Call the API from your server, script or CI.

Permissions

A token gets only the permissions you choose when you create it. The permissions of an existing token never grow: for new permissions create a new token.

In your account you can start from a ready-made purpose: «Read only», «CI: build a server», «Agent: catalog and my MCPs». Sensitive permissions are never part of a purpose.

A token can be limited to some of your servers: in the «Your servers» methods your other servers then look to it as if they did not exist (404). For CI create a separate token for each server.

A token can also be limited to IP addresses or networks — convenient for CI runners with fixed addresses. From any other address it gets 401 invalid_token.

Some actions are never available through the API — only in your account in the browser: changing the password or email, two-factor authentication, trusted devices, creating tokens, topping up the wallet, deleting servers and the account. The most sensitive of them also ask for your password.

Methods

Request and response schemas of every method are in the OpenAPI specification: api.mcpbay.pro/v1/openapi.json

Send request bodies as JSON with the Content-Type: application/json header. Most write methods answer 204 No Content; setting variables answers 200 with the names that were set; rebuild and cancel answer 202 Accepted — the work continues in the background.

Catalog — no token needed

• GET /v1/catalog/categories — categories
• GET /v1/catalog/servers — search: q, category, limit, cursor
• GET /v1/catalog/servers/{id} — a server card
• GET /v1/catalog/servers/{id}/tools — tools and their prices
• GET /v1/catalog/servers/{id}/trust — what mcpbay.pro checked about the server

Token

• GET /v1/token — permissions, limits and expiry of the current token
• DELETE /v1/token — revoke the current token

Your account

• GET /v1/me — profile account:read
• GET /v1/me/saved-servers — «My MCP» saved_servers:read
• POST /v1/me/saved-servers — add a server: {"server_id": 123} saved_servers:write
• DELETE /v1/me/saved-servers/{id} — remove a server saved_servers:write
• GET /v1/me/usage — usage across servers: days usage:read
• GET /v1/me/saved-servers/{id}/usage — usage of one server by tool and day usage:read
• GET /v1/me/notifications — notifications: limit, unread_only, cursor notifications:read
• POST /v1/me/notifications/read — mark as read: {"ids": [...]} or {"all": true} notifications:write

Your servers

• GET /v1/author/servers — servers you submitted, in any review status servers:read
• GET /v1/author/servers/{id} — one server servers:read
• GET /v1/author/servers/{id}/listing — is it shown in the catalog, and if not — why servers:read
• GET /v1/author/servers/{id}/tool-audit — result of the tool description check servers:read
• GET /v1/author/servers/{id}/deployment — hosting status deployments:read
• POST /v1/author/servers/{id}/deployment/rebuild — build the latest code and deploy it deployments:write
• POST /v1/author/servers/{id}/deployment/cancel — cancel the running build deployments:write
• GET /v1/author/servers/{id}/builds — build history deployments:read
• GET /v1/author/servers/{id}/builds/{build_id} — build log and findings deployments:read
• GET /v1/author/servers/{id}/builds/{build_id}/log — live build log from the since offset deployments:read
• GET /v1/author/servers/{id}/logs — recent lines of the server log deployments:read
• GET /v1/author/servers/{id}/secrets — variable names secrets:read
• PUT /v1/author/servers/{id}/secrets — set variables: {"secrets": {"NAME": "value"}}; a running server restarts once to apply them, staged: true means they apply at its next start secrets:write
• DELETE /v1/author/servers/{id}/secrets/{name} — delete a variable secrets:write
• GET /v1/author/servers/{id}/stats — tool calls: days revenue:read
• GET /v1/author/servers/{id}/revenue — earnings from paid calls: days revenue:read
• GET /v1/author/servers/{id}/tool-prices — tool prices servers:read
• PUT /v1/author/servers/{id}/tool-prices — set prices, all at once or none: {"items": [...]} pricing:write

Some write requests are safe to repeat: saving an already saved server does not add it twice, and a rebuild requested while a build is queued or running gets 409 build_in_progress instead of a second build.

Errors

Errors come as application/problem+json (RFC 9457). Rely on the code field — it is stable; the texts may change.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Request-Id: req_3f9c2a71b0d44e8a

{
  "type": "https://mcpbay.pro/api-docs.html#errors",
  "title": "Forbidden",
  "status": 403,
  "detail": "This token does not have the 'deployments:write' permission.",
  "code": "insufficient_scope",
  "request_id": "req_3f9c2a71b0d44e8a"
}

Some methods have their own codes, for example not_rebuildable (409, the server cannot be rebuilt in its current state), not_deployed (409, the server is not running on mcpbay.pro hosting), build_not_running (409), invalid_category, invalid_price or unknown_tool (400). The detail field explains each of them.

Every response has a Request-Id header, and every error has request_id. If you need help, send it to support@mcpbay.pro.

Rate limits

Up to 60 requests per minute per token; without a token — up to 30 per minute from one IP address. The RateLimit headers show how many requests are left:

RateLimit-Policy: "token";q=60;w=60
RateLimit: "token";r=42;t=18

Over the limit the API answers 429 with a Retry-After header — wait that many seconds and repeat.

Heavy operations have their own limits: rebuilds — a few per hour per server; server logs — once every 20 seconds per server. Repeated failed authentication from one address is blocked for a while.

Pagination

Lists return data, has_more and next_cursor. For the next page pass next_cursor as the cursor parameter with the same filters. The cursor is opaque: do not build or parse it.

{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "eyJvIjoyMCwiZiI6IjNhOWQifQ"
}

Example: rebuild a server from GitHub Actions

Create a token with the «CI: build a server» purpose, limited to this server, and save it as the MCPBAY_TOKEN secret of the repository. SERVER_ID is the id field from GET /v1/author/servers. A rebuild takes the latest commit of the branch set for hosting, not the tag itself, so tag a commit that is already on that branch. Rebuild on release tags rather than on every commit — this keeps you within the hourly build limit.

name: Deploy to mcpbay.pro
on:
  push:
    tags: ["v*"]

jobs:
  rebuild:
    runs-on: ubuntu-latest
    steps:
      - name: Rebuild the hosted server
        env:
          SERVER_ID: "123"
          MCPBAY_TOKEN: ${{ secrets.MCPBAY_TOKEN }}
        run: |
          curl --fail-with-body -X POST \
            "https://api.mcpbay.pro/v1/author/servers/$SERVER_ID/deployment/rebuild" \
            -H "Authorization: Bearer $MCPBAY_TOKEN"

The API answers 202 Accepted — the build runs in the background. Follow it with GET /v1/author/servers/{id}/builds (newest first) and its live log with GET …/builds/{build_id}/log?since=<next>.

For AI agents

Give an agent only the permissions its task needs — for example, the «Agent: catalog and my MCPs» purpose, or «Read only» if it must not change anything. Catalog search needs no token at all. An agent can read this page as Markdown (the Copy page menu above) and the OpenAPI specification.

If a token leaks

• Revoke it in your account → API tokens. The revocation takes effect with the very next request.
• No access to your account right now? A token can revoke itself — see the command below.
• When you change your password, you can revoke all tokens at once; resetting the password by email revokes them automatically.

curl -X DELETE https://api.mcpbay.pro/v1/token \
  -H "Authorization: Bearer $LEAKED_TOKEN"

Versions and changes

The version is part of the address: /v1. Within v1 we only add things — new methods, fields and permissions. Anything incompatible goes into /v2; v1 then keeps working for at least 6 months, and its responses carry Deprecation and Sunset headers.

Changelog

• September 2026 — the first version: catalog, token, your account, your servers.