Skip to main content

OAuth Setup

This page explains how authentication works on the Etalasse MCP server and how to connect an MCP client using OAuth sign-in.

Purpose​

With OAuth, remote MCP clients — such as Claude Code, Codex, or a ChatGPT connector — can sign in directly with an Etalasse Dashboard account. The server then resolves the authenticated user and shop automatically, so you do not need to copy or manage access tokens manually in normal usage.

Two layers of authentication​

Etalasse MCP keeps two concerns separate:

  • Transport auth — proves the MCP client is allowed to reach the server (an OAuth bearer token, or a shared bearer token for certain server-to-server integrations).
  • User auth — proves which user is acting. Identity comes from the Etalasse Dashboard login through the OAuth flow.

The shop scope is always derived from the authenticated Etalasse user — dashboard tools never accept another shop identity as free-form input.

Requirements​

  • the owner account of an Etalasse shop on the Growth plan or higher (sign in with email, Google, and 2FA when it is on)
  • an MCP client that supports remote HTTP MCP servers with OAuth
  • the Etalasse MCP endpoint URL for your environment

Discovery endpoints​

MCP clients discover the OAuth configuration automatically through standard metadata endpoints on the MCP server:

  • GET /.well-known/oauth-protected-resource
  • GET /.well-known/oauth-authorization-server

The server also supports dynamic client registration, Client ID Metadata Documents and token revocation, so most modern MCP clients can connect without manual client registration.

Authorization flow​

  1. The MCP client reads the protected resource metadata.
  2. The client reads the authorization server metadata.
  3. The client opens the authorization page (/oauth/authorize) in a browser.
  4. The browser opens the Connect an AI app page in the Dashboard (dashboard.etalasse.com/connect). If you are already signed in to the Dashboard, just tap Allow; if not, sign in as usual (email, Google, 2FA) and you come back to this page. Use another account lets you pick a different account. On Allow, the Dashboard creates an access token named after the app (for example Claude (connector)).
  5. The server issues an authorization code.
  6. The client exchanges the code for tokens at /oauth/token.
  7. The client calls the MCP endpoint (/mcp) with the returned bearer token.
OAuth sequence diagram: the MCP client reads metadata, opens the authorization page in the browser, you sign in, the client swaps the code for a token, then calls /mcp with the bearer tokenMCP clientYour browserEtalasse MCPGET /.well-known/oauth-protected-resourceGET /.well-known/oauth-authorization-server/oauth/authorizeDashboard email + passwordauthorization codePOST /oauth/tokenaccess token + refresh tokenPOST /mcp (Authorization: Bearer …)1234567
Steps 1 to 7 above, in order. The highlighted part is where you sign in in the browser; after that the client uses the bearer token for /mcp.

Steps 1 to 7 above, in order. The highlighted part is where you sign in in the browser; after that the client uses the bearer token for /mcp.

Access tokens are short-lived; clients renew them automatically through the refresh token (the offline_access scope), and the refresh token is replaced every time it is used. To disconnect, revoke the token in Settings › Access Tokens. The main scope for dashboard operations is etalasse:dashboard.

Connecting a client​

Codex​

Codex supports OAuth for remote streamable HTTP MCP servers. After adding the server to your configuration, run:

codex mcp login etalasse

Full steps are in Connect other AI apps.

Claude Code​

See Connect to Claude for Claude (web, desktop, mobile) and Claude Code.

ChatGPT​

See Connect to ChatGPT.

Gemini​

See Connect to Gemini for the Gemini app, Gemini Enterprise and Gemini CLI.

Cursor, VS Code and other MCP clients​

See Connect other AI apps.

Alternative: manual login​

Without OAuth (for example, for testing or internal automation), a client using a personal access token or the shared token can call the auth.dashboard_login tool and then reuse the returned accessToken in subsequent tool calls. OAuth is the recommended primary path for direct user clients; manual tokens should be treated as a fallback.

Common errors​

  • 401 Unauthorized when calling /mcp — the token has expired or you have not signed in. Repeat the OAuth flow in your client (for example, codex mcp login etalasse).
  • Allow is greyed out — only the shop owner can connect apps, and the shop must be on Growth or higher. With 2FA on, enter the 2FA code first.
  • "This connection request has expired" — a request is valid for 15 minutes. Start connecting again from your AI app.
  • Dashboard tools reject the request — make sure the OAuth session is active; dashboard tools only operate on the authenticated user's shop.