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​

  • an active Etalasse Dashboard account (email and password)
  • 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 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. You sign in with your Etalasse Dashboard email and password.
  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). 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

Claude Code​

Claude Code can use the same HTTP MCP endpoint and complete the OAuth flow when the server is configured as a remote MCP server. See Client Integration for an example configuration.

ChatGPT​

For ChatGPT app/connector flows, the server already exposes the required OAuth and MCP primitives. You still need to create the connector on the ChatGPT side pointing at the Etalasse MCP endpoint.

Alternative: manual login​

Without OAuth (for example, for testing or internal automation), a client 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).
  • Sign-in fails — verify your Dashboard email and password; use the same account you use in the Dashboard.
  • Dashboard tools reject the request — make sure the OAuth session is active; dashboard tools only operate on the authenticated user's shop.