Sign in with OAuth
How a client signs in to the Runner MCP server, which scopes it can ask for, and what to do when the sign-in fails.
Most clients do all of this for you. Read it when you build your own client, or when a sign-in fails.
The flow, in six steps
Call without a token
Send a JSON-RPC request with POST to https://api.runnerai.com/mcp. Without a token, Runner answers HTTP 401 with this header:
WWW-Authenticate: Bearer resource_metadata="https://api.runnerai.com/.well-known/oauth-protected-resource/mcp", scope="store:read store:write"
Read the resource metadata
It names the authorization server: https://www.runnerai.com/api/auth.
Register the client
Register at https://www.runnerai.com/api/auth/oauth2/register. Use a redirect URI on http://localhost, http://127.0.0.1, or http://[::1]. Runner accepts any port and path. Runner accepts 5 registrations each minute from one IP address.
Send the user to sign in, with PKCE
Use PKCE with S256 and send resource=https://api.runnerai.com/mcp. The user chooses the workspace and the access.
Call with the token
Send the access token in the Authorization: Bearer header. Runner answers each request with JSON and keeps no session. A GET request gets HTTP 405.
Refresh the token
An access token lasts 1 hour. Use the refresh token to get a new one. A refresh token expires after 30 days without use.
Scopes
| Scope | On the sign-in page | What the client can do |
|---|---|---|
store:read |
Read, always on | See store data, such as products, orders, and reports. |
store:write |
Make changes, starts off | Change store data, such as products, prices, and discounts. Ask for it only if your client changes data. |
Use the scopes from the resource metadata or the WWW-Authenticate header. The authorization server metadata also lists scopes for other Runner servers. If the client asks for them too, Runner removes them.
Rules for every client
- Call from your back end. Runner refuses requests that come from a web page on another site. Use your server, or a page on
localhost. - One workspace for each connection. For a second workspace, add the server again under another name and sign in again.
- Your permissions apply. Each call uses your Runner permissions and your plan. The list of tools depends on both.
If sign-in fails
| What you see | What to do |
|---|---|
{"error":"invalid_scope"} in the browser |
Ask for store:read, and store:write only if the client changes data. |
| This redirect URI cannot receive Merchant MCP codes. | The client sends the browser back to an app link or a web page. Use the mcp-remote bridge. |
| Request the Merchant MCP resource alone. | Send resource=https://api.runnerai.com/mcp, or use the mcp-remote bridge. |
| HTTP 429 when the client registers | More than 5 registrations in one minute from one IP address. Wait one minute, then try again. |
More errors are in Didn’t work?.