Authentication

How the Loop MCP Server authenticates merchants with OAuth 2.1 + PKCE.

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:

GET https://api.loopreturns.com/.well-known/oauth-protected-resource
GET https://api.loopreturns.com/.well-known/openid-configuration
GET https://api.loopreturns.com/.well-known/oauth-authorization-server

The response advertises Loop (https://api.loopreturns.com) as the OAuth authorization server, the supported scopes, and the endpoints below.

Authorization endpoints

Endpoint	Purpose
POST /oauth/register	Return the client metadata needed to start the MCP OAuth flow
GET /oauth/authorize	Begin the authorization flow
GET /oauth/callback	Complete the browser authorization flow
POST /oauth/token	Exchange the code for a bearer token

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

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:

POST /mcp HTTP/1.1
Host: api.loopreturns.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{ "jsonrpc": "2.0", "method": "tools/call", ... }

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

Endpoint	Limit
/.well-known/*	100/hour per IP
/oauth/register	50/hour per IP
/oauth/authorize	100/hour per IP
/oauth/token	100/hour per IP
/mcp (tool calls)	600/hour per authenticated user

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

Troubleshooting

The browser opens but I see 'Email not found'

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

Authentication succeeds but tool calls return 'Unauthorized'

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.

The MCP client says 'Token expired'

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.