Authentication

The Bizzy MCP server is a protected resource. Clients authenticate using OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591), following the MCP authorization specification. Modern MCP clients — Claude Desktop, Claude Code, Cursor, Windsurf, and the MCP Inspector — run the entire flow automatically. As an end user you only need to:

Point the client at https://mcp.bizzyco.ai.
Sign in to Bizzy when the consent screen opens in your browser.
Approve the consent screen, choosing which tool categories the client may use.

The rest of this page describes the flow in detail for client developers and for anyone debugging a connection.

How the flow works

Client → /mcp (or /sse)            (no token)
Server → 401 + WWW-Authenticate
Client → /.well-known/oauth-protected-resource/mcp   (route-scoped; host-level also available)
Client → /.well-known/oauth-authorization-server
Client → POST /oauth/register      (Dynamic Client Registration)
Client → /oauth/authorize          (browser, with PKCE code_challenge)
User   → consent screen
Server → redirect with auth code
Client → POST /oauth/token         (code + code_verifier)
Server → access_token (+ refresh_token if offline_access)
Client → /mcp or /sse              (Authorization: Bearer <token>)

The handshake is plain OAuth 2.1; no Bizzy-specific extensions are involved.

Discovery

The server publishes two host-derived metadata documents. A client discovers everything else from these.

Endpoint	Purpose
`/.well-known/oauth-protected-resource`	RFC 9728 protected-resource metadata. Lists the authorization server.
`/.well-known/oauth-authorization-server`	RFC 8414 authorization-server metadata. Lists `/oauth/register`, `/oauth/authorize`, `/oauth/token`, supported scopes, and PKCE methods.

You can fetch them directly:

curl -s https://mcp.bizzyco.ai/.well-known/oauth-protected-resource | jq
curl -s https://mcp.bizzyco.ai/.well-known/oauth-authorization-server | jq

401 response shape

A request to /mcp or /sse without a valid Bearer token returns HTTP 401 with a WWW-Authenticate header pointing back to a route-scoped protected-resource metadata URL on the same host:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.bizzyco.ai/.well-known/oauth-protected-resource/mcp", error="invalid_token", error_description="Missing or invalid access token"
Content-Type: application/json

{"error":"invalid_token","error_description":"Missing or invalid access token"}

The 401 — not a JSON-RPC error envelope — is the canonical signal that the client should run discovery and the OAuth flow. The resource_metadata URL is route-scoped (/mcp and /sse advertise their own metadata documents); a host-level document is also available at /.well-known/oauth-protected-resource for clients that prefer it.

Dynamic Client Registration

Clients register themselves at POST /oauth/register per RFC 7591. Registration is open (no admin approval required) but rate-limited to 10 requests per 60 seconds per IP, so clients should cache the returned client_id (and any client_secret) and reuse it across launches rather than re-registering every time. Prefer the OS credential store (Keychain on macOS, Credential Manager on Windows, libsecret on Linux) over a plaintext file on disk, especially for client_secret values.

PKCE

The server requires PKCE on every authorization request and only accepts the S256 code-challenge method. Plain PKCE is rejected — clients that send code_challenge_method=plain will fail the authorize step.

Resource indicator

The server requires an RFC 8707 resource parameter on every authorization request, and its value must identify this MCP server (the same origin you connect to, e.g. https://mcp.bizzyco.ai). This binds the issued access token’s audience to Bizzy so it can’t be replayed against another server. An authorize request that omits resource, or sends one pointing at a different origin, is rejected with an Invalid resource error. Modern MCP clients derive this from the server URL and send it automatically; custom clients must include it.

Scopes

Two scopes are advertised:

Scope	Required	Purpose
`mcp`	Yes	Access to the MCP transport endpoints.
`offline_access`	No	Issues a refresh token alongside the access token. Request only for persistent or background clients; omit for interactive one-shot use, since the 90-day refresh token is a longer-lived credential.

During consent the user also chooses which tool categories the client may call. The set of tools advertised over tools/list is filtered against that selection on every request.

Token lifetime

Token	TTL	Notes
Access token	60 min	Bearer token presented on `/mcp` and `/sse`.
Refresh token	90 days	Issued only when `offline_access` was granted; rotated on use.

Access tokens are refreshed via POST /oauth/token with grant_type=refresh_token. Refresh tokens rotate on every use per OAuth 2.1. The token endpoint is rate-limited to 10 requests per 60 seconds per IP; cache the access token for its lifetime rather than re-exchanging on every call.

Rate limits

Two limits apply to authenticated traffic, and they surface differently.

Tool calls: your plan’s per-minute limit

Every tools/call spends one request from your account’s MCP allowance:

Plan	MCP requests per minute
Free	10
Starter	30
Professional	100
Enterprise	300

The limit is also the burst capacity: you can spend your full per-minute allowance at once, and it replenishes continuously over the following minute. MCP and API allowances are independent — heavy API traffic never consumes your MCP capacity. See Understanding Limits for how rate limits fit into your plan. A throttled tool call is not an HTTP error. The request succeeds at the transport level and the throttle is reported in the JSON-RPC envelope, so clients must inspect the response body rather than the status code alone:

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32004,
        "message": "Rate limit exceeded",
        "data": { "retryAfter": 6 }
    }
}

Wait data.retryAfter seconds before retrying that call. Other methods (tools/list, ping, and the rest of the protocol) do not spend from this allowance.

Transport: per-(user, client) backstop

Independently, /mcp and /sse accept at most 600 requests per 60 seconds per (user, client) as an abuse backstop. Its ceiling sits above every plan’s tool-call limit, so ordinary use never reaches it. A throttled request here is HTTP 429 with the same JSON-RPC error body and a Retry-After header. The server does not emit X-RateLimit-* headers on either surface.

Getting Started

Agent resources

How the flow works

Discovery

401 response shape

Dynamic Client Registration

PKCE

Resource indicator

Scopes

Token lifetime

Rate limits

Tool calls: your plan’s per-minute limit

Transport: per-(user, client) backstop

Reference

​How the flow works

​Discovery

​401 response shape

​Dynamic Client Registration

​PKCE

​Resource indicator

​Scopes

​Token lifetime

​Rate limits

​Tool calls: your plan’s per-minute limit

​Transport: per-(user, client) backstop

​Reference

How the flow works

Discovery

401 response shape

Dynamic Client Registration

PKCE

Resource indicator

Scopes

Token lifetime

Rate limits

Tool calls: your plan’s per-minute limit

Transport: per-(user, client) backstop

Reference