Authentication & Scopes

Personal Access Tokens (PATs)

PATs are long-lived, per-organization bearer tokens. Every MCP request carries one in the Authorization header:

Authorization: Bearer vbl_pat_live_<32 urlsafe chars>

Token Format

At creation the full token is shown once. Only a SHA256 hash of the raw value is persisted — a stolen database row cannot be replayed as a token.

Lifecycle

OAuth Connectors

Claude.ai, Claude Desktop connectors, and ChatGPT cannot send a static token. They connect through OAuth 2.1 instead: add https://mcp.vaybel.com/ as a custom connector, sign in to Vaybel, and approve one workspace and a scope set on the consent screen. The resulting access is org-pinned exactly like a PAT, shows up under Connected apps in Settings, and can be revoked there. Details in Connectors.

Where To Store Tokens

Use one canonical local secret: VAYBEL_PAT.

For Claude Code, prefer storing the token in Claude Code settings so it is available to both the Vaybel MCP server and the official Vaybel Skills plugin:

{
  "env": {
    "VAYBEL_PAT": "vbl_pat_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Then reference it from MCP config instead of pasting the token into the config file:

{
  "mcpServers": {
    "vaybel": {
      "type": "http",
      "url": "https://mcp.vaybel.com/",
      "headers": {
        "Authorization": "Bearer ${VAYBEL_PAT}"
      }
    }
  }
}

Scopes

Every tool declares the scope(s) it requires. A PAT missing the scope gets a missing_scope tool error. The dashboard token creator selects all public scopes by default — uncheck only what you want to deny.

All scopes. The creator defaults to an All scopes switch that stores the literal ["*"] wildcard. Unlike an explicit scope list — which is fixed at mint time, so a scope added to the platform later isn't granted until you create a fresh token or edit the token's scopes — an all-scopes token grants every current scope and any scope added later, so it never needs recreating for new tools. Turn the switch off to pick an explicit subset.

Read scopes

Write scopes

PrintGen buyer scopes

Tokens for the PrintGen buyer surface carry a smaller, buyer-facing scope set:

Plan gates

Most of the MCP surface is a paid capability. A small read-only set works on any plan, most tools require Starter or higher, and the Growth-plan feature areas are gated at Growth:

Gated calls fail with a clear plan_required: ... error rather than returning empty data. The error names no plan; each tool's tier is shown as a Plan chip in the Tool Reference.

Rate Limits

Rate limits apply per-PAT, per-tool, on a fixed 60-second window. Hitting one raises a rate_limited error carrying a retry after Ns hint.

Credit balance provides the finer gating for billable tools — you'll hit insufficient_credits before a rate limit on a real workload.

Credit Charging

Most tools are free. A handful charge from the same credit balance your dashboard uses — no separate developer meter.

Work that is charged when it completes costs nothing if it fails. Product photos from mockup.generate at quality="standard" are free, and dry_run=true returns the exact quote before anything is charged. credits.list_costs returns the same prices.

Three pre-flight gates prevent surprises:

1. Out-of-credit calls fail fast — billable tools run a balance check before dispatching any background work.
2. Billable tools accept an idempotency_key; sending the same key on a retry returns the cached result, so a flaky-network loop doesn't double-bill (or double-publish).
3. trend.generate_concept short-circuits to free when the concept is already cached.

Read tools and status polls are always free.

Errors You Might See

Tool errors arrive as MCP tool results (not HTTP status codes — only authentication failures are HTTP 401). Machine-readable errors are prefixed with a stable code:

Errors without a code prefix are plain validation messages (e.g. prompt is required).