Skip to main content
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:
  1. Point the client at https://mcp.bizzyco.ai.
  2. Sign in to Bizzy when the consent screen opens in your browser.
  3. 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.
EndpointPurpose
/.well-known/oauth-protected-resourceRFC 9728 protected-resource metadata. Lists the authorization server.
/.well-known/oauth-authorization-serverRFC 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.

​
Scopes

Two scopes are advertised:
ScopeRequiredPurpose
mcpYesAccess to the MCP transport endpoints.
offline_accessNoIssues 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

TokenTTLNotes
Access token60 minBearer token presented on /mcp and /sse.
Refresh token90 daysIssued 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.

​
Rate limits on the transport

Once authenticated, /mcp and /sse are rate-limited to 100 requests per 60 seconds per (user, client). A throttled response is HTTP 429 with a JSON-RPC error body (code: -32004, message: "Rate limit exceeded") and a Retry-After header. The server does not emit X-RateLimit-* headers.

​
Reference

Last modified on May 30, 2026