Skip to main content
The Loop MCP Server uses OAuth 2.1 with PKCE for authentication and publishes authorization server metadata following RFC 8414. Most MCP clients handle this flow for you — this page exists for integrators who want to understand how it works under the hood.
This is not the same OAuth flow used by the REST API. REST API OAuth is for partner integrations that act on behalf of merchants. MCP OAuth is initiated by the merchant themselves through their MCP client.

​
Discovery

When an MCP client first connects to https://api.loopreturns.com/mcp, it fetches the protected resource metadata to discover the authorization server:
The response advertises Loop (https://api.loopreturns.com) as the OAuth authorization server, the supported scopes, and the endpoints below.

​
Authorization endpoints

All four endpoints live under https://api.loopreturns.com.

​
Redirect URI validation

POST /oauth/register returns Loop’s pre-configured client_id. It does not register your redirect URI as a trusted value. GET /oauth/authorize validates redirect_uri against a fixed allowlist of known client patterns. Loop accepts:
  • The custom schemes claude://, cursor://, and vscode://
  • HTTPS hosts for approved clients, including claude.ai, claude.com, chatgpt.com, chat.openai.com, vscode.dev, and global.consent.azure-apim.net for Microsoft Copilot Studio and Power Platform custom connectors
  • http://localhost with an explicit port, for desktop and CLI clients
Authorize rejects every other redirect URI, including URIs echoed back by registration. If your client authenticates through your own domain, contact your Loop point of contact. Loop adds approved redirect domains to the allowlist. See supported clients.

​
Flow overview

​
Multi-tenant shop resolution

A single email can be associated with multiple Loop shops. The MCP OAuth flow resolves the right shop in one of three ways:
  1. login_hint provided. The client passes the email up front; Loop looks up the associated shops.
  2. Email form. If no hint is provided, Loop shows an email input form.
  3. Shop selector. If the email is associated with more than one shop, Loop shows a shop selection form before sign-in continues.
If no shops are found for the email, Loop continues the sign-in flow without revealing whether the email matched a Loop user. This prevents email enumeration through the OAuth flow. The selected shop is encoded into the resulting session so every tool call is scoped to that shop.

​
Token handling

Loop returns a signed bearer token that MCP clients present on each tool call. Clients should treat this token as opaque: store it securely, send it only to Loop, and reconnect when the client reports that the session has expired.

​
Using the token

Pass the token in the Authorization header on every MCP request:
Loop validates the token, resolves the selected shop, and loads the corresponding user before running any MCP tool.

​
Permissions

Once authenticated, the user is subject to the same role-based permissions that govern their access to the Loop Admin. Each MCP tool declares the permissions it requires (OR logic — at least one is sufficient). If a user lacks every required permission, the tool returns an authorization error and is hidden from the assistant’s tool catalog where possible.

​
Rate limits

Exceeded limits return 429 Too Many Requests with a Retry-After header.

​
Troubleshooting

Loop didn’t find any shops associated with the email you submitted. Confirm the email matches a user record in your Loop Admin (under Settings → Team).
The token is valid but your user doesn’t have permission for the tool you’re invoking. Check the user’s role in Settings → Team and grant the necessary permissions.
Reconnect the server in your MCP client to start a fresh OAuth flow.

​
Next steps

Get Started

Connect Claude, Cursor, or VS Code Copilot to the Loop MCP Server.

Overview

See the full list of tools the MCP server exposes.