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

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. Scopes added to the platform after a token was minted are not retroactively granted: create a fresh token to pick up new scopes.

Read scopes

Write scopes

Plan gates

The MCP surface is a paid capability. Every tool requires Starter or higher, with the Growth-plan feature areas gated at Growth:

Gated calls fail with a clear plan_required: ... error rather than returning empty data, so agents can surface the upgrade path. 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.

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