Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt

Use this file to discover all available pages before exploring further.

The Loop MCP Server is currently in preview. Authentication details described here may evolve before general availability.
The Loop MCP Server uses OAuth 2.1 with PKCE for authentication, following RFC 9728 (OAuth 2.0 Protected Resource Metadata). 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
The response advertises Loop as the OAuth authorization server, the supported scopes, and the endpoints below.

​
Authorization endpoints

EndpointPurpose
POST /oauth/registerDynamic Client Registration (RFC 7591)
GET /oauth/authorizeBegin the authorization flow
GET /oauth/callbackReceive the upstream authorization code
POST /oauth/tokenExchange the code for an id_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 redirecting to Auth0.
If no shops are found for the email, Loop performs a blind redirect to Auth0 without an organization context. This prevents email enumeration through the OAuth flow. The selected shop’s organization ID is included in the upstream Auth0 request and returned in the org_id claim of the issued id_token.

​
Token format

Loop issues a signed id_token (not an opaque access token). The token is a standard JWT with these notable claims:
ClaimDescription
issLoop’s Auth0 tenant (https://loopreturns-orgs.us.auth0.com/)
audThe MCP client’s client_id
subThe Auth0 user ID
org_idThe Auth0 organization ID, mapped to a Loop shop
emailThe merchant’s email address
expToken expiration (1 hour from issue)
Loop swaps Auth0’s encrypted access_token for the signed id_token before returning it to the client. This is intentional — MCP clients need a verifiable JWT they can present as a Bearer token, and the encrypted Auth0 access token is opaque.

​
Using the token

Pass the id_token as a Bearer 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", ... }
The server verifies the JWT signature against Auth0’s JWKS (cached for one hour), maps org_id to a Loop shop, and loads the corresponding user.

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

​
Token lifetime and refresh

PropertyValue
id_token lifetime1 hour
Refresh tokensNot currently issued
When a token expires, the MCP client re-runs the authorization flow. Most clients cache the client_id from dynamic registration and complete the refresh in the background.

​
Rate limits

EndpointLimit
/.well-known/*100/hour per IP
/oauth/register50/hour per IP
/oauth/authorize100/hour per IP
/oauth/token100/hour per IP
/mcp (tool calls)600/hour per authenticated user
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 id_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.
id_tokens expire after one hour. 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.