Saltar para o conteúdo
DocsBuild with Runner
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Open Runner

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?.

Última atualização a 19 de novembro de 2026

Esta página foi útil?