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

# 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](https://datatracker.ietf.org/doc/html/rfc8414). Most MCP clients handle this flow for you — this page exists for integrators who want to understand how it works under the hood.

<Info>
  This is **not** the same OAuth flow used by the [REST API](/api-reference/authentication#oauth-2-0-authentication). 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.
</Info>

## 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

```mermaid theme={null}
sequenceDiagram
  participant Client as MCP Client
  participant Loop as Loop MCP Server
  participant User as Merchant (browser)
  participant IdP as Loop identity provider

  Client->>Loop: GET /.well-known/oauth-protected-resource
  Loop-->>Client: Resource + auth server metadata
  Client->>Loop: POST /oauth/register (client metadata)
  Loop-->>Client: client_id
  Client->>User: Open /oauth/authorize?... in browser
  User->>Loop: GET /oauth/authorize
  Loop->>User: Email form (or login_hint)
  User->>Loop: Submit email
  Loop->>Loop: Resolve email → shop(s)
  Loop->>IdP: Redirect to sign in
  IdP->>User: Login prompt
  User->>IdP: Credentials
  IdP->>Loop: GET /oauth/callback?code=...
  Loop->>Client: Redirect with code
  Client->>Loop: POST /oauth/token (code + PKCE verifier)
  Loop-->>Client: Bearer token
  Client->>Loop: MCP request with bearer token
```

## 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:

```http theme={null}
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

<AccordionGroup>
  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="The MCP client says 'Token expired'">
    Reconnect the server in your MCP client to start a fresh OAuth flow.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Get Started" icon="play" href="/mcp/getting-started">
    Connect Claude, Cursor, or VS Code Copilot to the Loop MCP Server.
  </Card>

  <Card title="Overview" icon="robot" href="/mcp/overview">
    See the full list of tools the MCP server exposes.
  </Card>
</CardGroup>