Authentication

OAuth 2.1 sign-in, discovery endpoints, and how a token maps to a studio.

Studio has no API keys. Every MCP client authenticates with OAuth 2.1 against Studio’s own authorization server (better-auth), which also owns the Google sign-in the web app uses. Tokens belong to a user, so a tool call can never do more than that user could do in the UI.

The flow

1. Unauthenticated request

   POST /mcp without a bearer token returns 401 with:

   WWW-Authenticate: Bearer resource_metadata="https://studio-api.growhub.ai/.well-known/oauth-protected-resource"
   
2. Discovery

   The client fetches that resource metadata, then /.well-known/oauth-authorization-server to find the authorize, token, and registration endpoints.

3. Client registration

   Clients that have no pre-registered id use dynamic client registration (RFC 7591) at /api/auth/mcp/register. This is what makes one-click connect work.

4. Authorize

   The browser opens /api/auth/oauth2/authorize. With no active session, Studio redirects to https://studio.growhub.ai/login for Google sign-in, then back into the authorize step.

5. Consent and token

   You approve the client, and Studio issues an access token (PKCE-protected authorization code exchange).

6. Authenticated calls

   The client sends Authorization: Bearer <token> on every POST /mcp request. Studio resolves the token to a user, then to a studio.

Endpoints

Endpoint	Purpose
POST /mcp	The MCP endpoint itself (streamable HTTP)
/.well-known/oauth-protected-resource	Points clients at the authorization server
/.well-known/oauth-authorization-server	OAuth 2.1 metadata document
/api/auth/mcp/register	Dynamic client registration
/api/auth/oauth2/authorize	Authorization endpoint
https://studio.growhub.ai/login	Google sign-in page

Swap the host for http://localhost:8787 in local development.

Which studio do tools act on?

A user can belong to several studios. The MCP session resolves to one:

1. The session’s active studio, if the token’s user is a member of it.
2. Otherwise, the user’s first studio membership.

MCP has no studio switcher yet. If you belong to more than one studio and the tools are writing to the wrong one, switch the active studio in the web app — then reconnect the client so the new session picks it up. Explicit per-tool studio selection is planned.

If the user has no membership at all, /mcp returns 403 No studio membership.

Roles

Studio roles come from the workspace (owner, admin, member). Most tools are open to any member. Two are restricted:

Tool	Required role
connect_platform	owner or admin
disconnect_platform	owner or admin

A member without the role gets a forbidden tool error.

Token lifetime and revocation

Access tokens are issued and stored by your MCP client; Studio keeps the authorization records in its own database. Signing out of the web app does not revoke a client’s token — remove the server from the client to cut its access.