Skip to main content
Gumnut supports OAuth for user-facing integrations that need delegated access. The flow uses Clerk for authorization, and MCP hosts are one supported client. For SDKs and scripts, use an API key instead.

​
Custom integrations

For a user-facing OAuth client, use the Gumnut OAuth endpoints to start and complete the authorization-code flow:
  1. Call GET https://api.gumnut.ai/api/oauth/auth-url with your exact redirect_uri and, for public clients, a PKCE code_challenge plus code_challenge_method=S256.
  2. Redirect the user to the returned authorization URL.
  3. Read the code and state from your callback URL.
  4. Send them to POST https://api.gumnut.ai/api/oauth/exchange, along with the PKCE code_verifier when one was used.
  5. Send the returned access_token as a Bearer token on API requests.
Keep the state value tied to the user’s session, use PKCE for public clients, and register redirect URIs exactly.

​
First-time provisioning

When a user completes OAuth for the first time, Gumnut verifies the current Clerk identity before creating the user’s local Gumnut account. Existing local users continue through the normal token-exchange flow. The POST /api/oauth/exchange response tells you how to recover when that verification cannot complete: These errors are returned only while Gumnut is provisioning a new local user; they do not indicate that the authorization-code parameters are malformed.

​
MCP hosts

Connect an MCP host to:
In hosts with built-in OAuth support, this is usually the only server URL you need to enter. For step-by-step host configuration, see MCP setup.

​
Discovery flow

  1. The MCP host fetches Gumnut’s protected-resource metadata:
  2. That metadata identifies Clerk as the authorization server.
  3. The host fetches Clerk’s authorization-server metadata to discover the authorization, token, and supported client-registration endpoints.
  4. The host completes the authorization-code flow with PKCE, manages the tokens, and sends the access token in the Authorization header on MCP requests.

​
MCP request authentication

The MCP transport itself is protected. After discovery, the host must send a valid bearer credential on every HTTP request, including initialize, tools/list, notifications, resource requests, and tool calls. A missing, invalid, expired, or revoked credential receives 401 Unauthorized with a WWW-Authenticate challenge. Browser cookies are not accepted as a fallback for MCP bearer authentication. OAuth discovery metadata and CORS preflight requests are public. A valid first-time Clerk bearer can complete discovery before a local Gumnut account exists; the normal REST flow performs provisioning when the user uses a tool.
For MCP discovery, do not construct the provider’s authorization or token endpoint URLs under api.gumnut.ai. Gumnut does not publish /oauth/authorize, /oauth/token, or /oauth/revoke endpoints; follow the discovery metadata so the host uses Clerk’s current endpoints. The custom integration endpoints documented above are separate Gumnut endpoints.

​
Scopes

The protected-resource metadata currently advertises these identity and session scopes:
  • profile
  • email
  • offline_access
These are Clerk scopes, not granular Gumnut resource permissions. Gumnut does not currently publish action- or resource-specific OAuth scopes. OAuth access tokens currently grant the authenticated user’s full Gumnut API access; the advertised Clerk scopes do not limit actions or libraries. If your integration needs credentials limited to selected actions or libraries, use a scoped API key in a server-side integration instead.

​
Token handling for custom integrations

The access_token returned by /api/oauth/exchange is a Gumnut JWT. There is no refresh-token exchange in this flow. Replace your stored token whenever an authenticated response includes an x-new-access-token header. If the token expires before it can be refreshed, restart the authorization flow.

​
Token handling for MCP hosts

The MCP host owns token storage, refresh, and logout behavior. Follow the authorization server’s returned token metadata and let the host’s OAuth client manage renewal.
Never ask users to paste access tokens into your application. Use the MCP host’s OAuth flow, keep redirect URIs exact, verify OAuth state, and use PKCE.

​
Troubleshooting

​
The host does not open a sign-in or consent page

Confirm that the server URL is exactly https://api.gumnut.ai/mcp and that the host supports OAuth discovery for remote MCP servers. Do not configure guessed Gumnut OAuth endpoints manually.

​
Authorization fails with a redirect error

The redirect URI must match the OAuth client registration exactly, including scheme, host, path, and trailing slash.

​
Authorization fails with invalid_scope

Use the scopes discovered from the server. Do not invent Gumnut action or resource scopes; they are not part of the supported Clerk-backed flow.

​
The MCP connection returns 401 Unauthorized

Disconnect and reconnect the server in the host so it can obtain a fresh token. If the problem persists, see MCP troubleshooting.