Authentication and Scopes

JoggAI MCP uses OAuth 2.0 Authorization Code with PKCE. The browser flow authenticates your JoggAI account, lets you select a Space, and asks you to approve scopes before the client receives a token. Public MCP access does not require copying a JoggAI API key into an agent.

OAuth flow

Discover the protected resource

The client connects to https://api.jogg.ai/mcp. An unauthenticated response points it to JoggAI protected resource and authorization metadata.

Authorize the client

The client opens the JoggAI authorization page with PKCE S256, resource=https://api.jogg.ai/mcp, and its exact registered redirect URI.

Choose a Space and approve scopes

The selected Space determines which private resources are visible and which billing account generation tools use.

Receive a resource-bound token

The access token audience is https://api.jogg.ai/mcp. The client stores access and refresh tokens in its own credential store.

The resource value must remain identical during authorization, code exchange, and refresh. A token issued for a JoggAI plugin or REST API has a different audience and cannot be used with MCP.

Discovery endpoints

Metadata	URL
Protected resource	`https://api.jogg.ai/.well-known/oauth-protected-resource`
MCP path-specific metadata	`https://api.jogg.ai/.well-known/oauth-protected-resource/mcp`
OpenID configuration	`https://api.jogg.ai/.well-known/openid-configuration`
JSON Web Key Set	`https://api.jogg.ai/.well-known/jwks.json`

Tool scopes

tools/list only returns tools allowed by the current token. JoggAI checks the scope again on every tools/call.

Scope	Capability
`openid`	Identify the authorized JoggAI user
`account.read`	Read account information for the selected Space
`quota.read`	Read the remaining quota of the actual billing account
`catalog.read`	List avatars, voices, music, templates, and visual styles
`asset.read`	Read authorized asset metadata when supported
`asset.write`	Request signed asset uploads
`script.generate`	Submit and inspect AI script jobs
`image.generate`	Submit and inspect avatar image generation
`video.generate`	Submit and inspect video, motion, lip sync, and translation jobs
`product.read`	Read products, previews, and product results
`product.write`	Create or update products
`webhook.read`	List webhook endpoints and supported events
`webhook.write`	Create, update, or delete webhook endpoints

Approving a scope makes matching tools discoverable; it does not bypass JoggAI Space membership, ownership, plan, quota, resource, or request validation.

Registered client redirects

JoggAI does not accept wildcard redirect URIs or arbitrary dynamic client registration during controlled beta.

Client	Redirect behavior
Codex	Native loopback IP, dynamic port, and resource-specific callback path
Claude Code	`http://localhost:5555/callback`
Cursor desktop	`http://localhost:8787/callback`
Cursor agents	`https://www.cursor.com/agents/mcp/oauth/callback`
ChatGPT	`https://chatgpt.com/connector_platform_oauth_redirect`

Codex should choose its own loopback port and path. Do not override it with localhost, a private devbox hostname, or a custom HTTPS callback.

Authorization errors

401 Unauthorized: credentials are missing, invalid, expired, revoked, or bound to the wrong resource. Run the client’s login flow again.
403 Forbidden: authentication succeeded but the required scope or Space permission is missing. Reauthorize only if that permission should be granted.
Redirect mismatch: the client sent a callback that was not registered exactly. Confirm the client and deployment configuration before retrying.

Never send access tokens, refresh tokens, authorization codes, API keys, or signed upload URLs to support.

​OAuth flow

​Discovery endpoints

​Tool scopes

​Registered client redirects

​Authorization errors

OAuth flow

Discovery endpoints

Tool scopes

Registered client redirects

Authorization errors