A connection always acts for one signed-in customer of one store. Nobody signs in for you: the first time your client connects, it opens the store’s sign-in page in your browser, and the access you approve there is all the client gets.
Signing in
- Your client opens the store’s sign-in page. It shows the store’s name, icon and colors, the app asking (Claude, ChatGPT or Perplexity are named as such; any other app by the name it gave itself, marked unverified until the store verifies it) and where it sends you back once you’re done.
- You sign in with your email. Enter the address you use at the store, then the code mailed to you; a quick check that you’re not a bot may run first. You can sign in with Google instead.
- You choose what the app may do. The consent screen lists what the app asked for. Pick Full access to grant all of it, or Read-only to let it read without changing anything (offered when it asked to read and more).
- You’re sent back to your client, which is now connected.
Signing in here signs you in to this authorization alone: it never signs you in to the store’s site, and signing out of the store’s site leaves the connection as it is.
The customer MCP works for the customers of every store, whatever the store’s plan.
What an app may ask for
Each permission is a scope. The consent screen names each one the app asks for, as below, and the app lists only the tools its scopes cover.
| Scope | On the consent screen | Tools it opens |
|---|---|---|
read |
See your purchases, subscriptions and progress, and read your unlocked content | Every tool that reads, and the store’s prompts |
profile:write |
Change your name and preferences | update_profile, mark_notifications_read, delete_notifications, update_notification_settings |
progress:write |
Update your progress | complete_entry |
quiz:write |
Take quizzes for you | start_attempt, save_attempt, submit_attempt, forfeit_quiz |
review:write |
Write and delete your reviews | write_review, delete_review |
subscription:write |
Cancel and resume your subscriptions | cancel_subscription, resume_subscription, change_subscription_plan |
Two tools need no scope at all, so every connection has them: get_store and verify_certificate. An app may also ask for checkout:write (“Start purchases for you”), which the store’s API uses; it opens no MCP tool, and the consent screen warns about it for an app the store hasn’t verified.
How long a connection lasts
- The client holds an access token, which lasts an hour, and a refresh token, which lasts 30 days. Every refresh hands it a new pair and retires the old refresh token, so a connection you keep using stays signed in; one unused for 30 days asks you to sign in again.
- A token works for the store it was issued for, and only on its MCP server: it can’t be used on another store, or on the store’s API.
- Disconnecting it under Connected apps in your account on the store’s site (
/account/connected-apps) ends its access at once: its tokens are revoked, and its next call is refused. - Removing the connector or server in your client stops it using the store. A client that revokes its token when you remove it ends its access at once; otherwise its access ends when its last access token expires, within the hour, as long as it no longer holds the refresh token.
For developers
This is the flow every client above runs. It is standard MCP authorization: OAuth 2.1 with dynamic client registration (RFC 7591), PKCE (S256 only), protected resource metadata (RFC 9728) and authorization server metadata (RFC 8414). A client built on an MCP SDK gets all of it from the SDK; the requests below show what goes over the wire, for the store shop.example.com on its own host.
1. Find the authorization server
A request with no token is refused with 401 and a pointer to the endpoint’s metadata:
POST /mcp HTTP/1.1
Host: shop.example.com
Content-Type: application/json
Accept: application/json, text/event-stream
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://shop.example.com/.well-known/oauth-protected-resource/mcp"curl https://shop.example.com/.well-known/oauth-protected-resource/mcp{
"resource": "https://shop.example.com/mcp",
"authorization_servers": ["https://customer-auth.sherpo.io/s/shop.example.com"],
"scopes_supported": ["read", "profile:write", "review:write", "quiz:write", "progress:write", "subscription:write"],
"bearer_methods_supported": ["header"],
"resource_name": "shop.example.com on Sherpo"
}scopes_supported lists the scopes the MCP tools and prompts use. Then read the authorization server’s metadata. On the store’s host it names the store’s own endpoints (the grants an MCP client uses are authorization_code and refresh_token; the store’s own sites use the others):
curl https://shop.example.com/.well-known/oauth-authorization-server{
"issuer": "https://customer-auth.sherpo.io/s/shop.example.com",
"authorization_endpoint": "https://shop.example.com/authorize",
"token_endpoint": "https://shop.example.com/token",
"registration_endpoint": "https://shop.example.com/register",
"revocation_endpoint": "https://shop.example.com/revoke",
"response_types_supported": ["code"],
"response_modes_supported": ["query"],
"grant_types_supported": ["authorization_code", "refresh_token", "…"],
"code_challenge_methods_supported": ["S256"],
"token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
"revocation_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
"scopes_supported": ["read", "profile:write", "checkout:write", "review:write", "quiz:write", "progress:write", "subscription:write"],
"authorization_response_iss_parameter_supported": true
}The issuer is https://customer-auth.sherpo.io/s/{store} for both addresses of the server. Connected at https://mcp.sherpo.io/s/{store} instead, the protected resource metadata is at https://mcp.sherpo.io/.well-known/oauth-protected-resource/s/{store} (and .../s/{store}/mcp for the /mcp form), and the authorization server’s at https://customer-auth.sherpo.io/.well-known/oauth-authorization-server/s/{store}, with its endpoints under the issuer (/authorize, /token, /register, /revoke). Follow the resource_metadata the 401 names: the metadata at https://mcp.sherpo.io/.well-known/oauth-protected-resource belongs to the merchant MCP server, so a client that skips it and reads the host’s root finds the wrong server. Prefer the store’s own address, where every document is at the root.
2. Register the client
curl https://shop.example.com/register \
-H 'content-type: application/json' \
-d '{
"client_name": "My study app",
"redirect_uris": ["http://127.0.0.1:8976/callback"],
"token_endpoint_auth_method": "none"
}'{
"client_id": "CLIENT_ID",
"client_id_issued_at": 1793678400,
"client_name": "My study app",
"redirect_uris": ["http://127.0.0.1:8976/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"token_endpoint_auth_method": "none",
"scope": "read profile:write checkout:write review:write quiz:write progress:write subscription:write"
}token_endpoint_auth_methodisnone(a public client, the usual choice), orclient_secret_basicorclient_secret_postfor a client that keeps a secret: the answer then carriesclient_secret, shown once. PKCE is required either way.- A client that names no
scopemay ask for every scope listed inscope. The name is cleaned and cut to 120 characters; the answer says what was kept. - Registrations are per store: register once with each store you connect to. A registration that hasn’t completed a sign-in within a day lapses, and one the store hasn’t verified that holds no live token and goes unused for 30 days is removed. When
/tokenanswersinvalid_client, register again.
3. Send the customer to sign in
Open the authorization endpoint in the customer’s browser, with a PKCE challenge (S256) and the endpoint as resource:
https://shop.example.com/authorize
?response_type=code
&client_id=CLIENT_ID
&redirect_uri=http%3A%2F%2F127.0.0.1%3A8976%2Fcallback
&scope=read%20progress%3Awrite
&state=STATE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
&resource=https%3A%2F%2Fshop.example.com%2Fmcpresource is the server’s address as you connect to it: https://{store}/mcp, or https://mcp.sherpo.io/s/{store} (its /mcp form too). A token for any of them works on all of them. Once the customer approves, the browser comes back to redirect_uri with code, state and iss; check that iss is the issuer and state is yours. A refusal comes back as error (access_denied when the customer declines).
4. Exchange the code
curl https://shop.example.com/token \
-d grant_type=authorization_code \
-d code=CODE \
-d redirect_uri=http://127.0.0.1:8976/callback \
-d client_id=CLIENT_ID \
-d code_verifier=CODE_VERIFIER \
-d resource=https://shop.example.com/mcp{
"access_token": "ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "REFRESH_TOKEN",
"scope": "read progress:write"
}scope is what the customer granted, which may be less than you asked for (Read-only grants read alone). Send the token on every request to the endpoint as Authorization: Bearer ACCESS_TOKEN.
5. Refresh and revoke
curl https://shop.example.com/token \
-d grant_type=refresh_token \
-d refresh_token=REFRESH_TOKEN \
-d client_id=CLIENT_IDThe answer has the same shape, with a new refresh token: keep it and drop the old one, which no longer works. When the customer disconnects, revoke the token (RFC 7009): revoking either the access or the refresh token ends the connection.
curl https://shop.example.com/revoke \
-d token=REFRESH_TOKEN \
-d client_id=CLIENT_IDA client with a secret authenticates each /token and /revoke request with it, by HTTP Basic or in the body, as it registered.
Errors come back as OAuth’s:
- At the authorization endpoint, once the client and its redirect are accepted, as
erroron the redirect:access_deniedwhen the customer declines,invalid_scopefor a scope the app may not hold,invalid_targetfor aresourcethat isn’t this store’s server,invalid_requestfor a malformed request,unsupported_response_typefor anyresponse_typebutcode,unauthorized_clientwhen the registration lapsed or was removed meanwhile (register again),temporarily_unavailablewhen too many calls came in (try again later), andserver_errorfor a failure on Sherpo’s side. Before that (an unknown client, a redirect it didn’t register), the customer sees an error page instead and nothing is redirected. - At the token endpoint, as JSON:
invalid_grantfor a code or refresh token that is wrong, used or expired (sign the customer in again),invalid_client(register again),invalid_request,unsupported_grant_type, andtemporarily_unavailablewithRetry-Afterwhen too many calls or refused requests came from your network, or503while the store is unavailable.server_errormeans the failure was on Sherpo’s side; try again.