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

# Getting Started

> Connect an MCP client to the Loop MCP Server.

This guide walks you through connecting an MCP-compatible client — Claude Desktop, Cursor, VS Code Copilot, or any other client that speaks the [Model Context Protocol](https://modelcontextprotocol.io) — to your Loop Returns account.

## Prerequisites

* A Loop Returns account in good standing
* A user account with the permissions you want the assistant to be able to use (the MCP server enforces the same role-based permissions as the [Loop Admin](https://admin.loopreturns.com))
* An MCP-compatible client installed locally

## The Loop MCP endpoint

```
https://api.loopreturns.com/mcp
```

All MCP traffic goes to that single URL. Authentication is negotiated automatically by the client through the [OAuth Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) discovery endpoint at `/.well-known/oauth-protected-resource`.

## Connect a client

<Tabs>
  <Tab title="Claude Desktop">
    Claude Desktop's local developer config connects to local command-based MCP servers. Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) to bridge Claude Desktop to Loop's hosted MCP endpoint.

    1. Open **Settings → Developer → Edit Config** in Claude Desktop.
    2. Add Loop to your `mcpServers` block:

    ```json theme={null}
    {
      "mcpServers": {
        "loop-returns": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://api.loopreturns.com/mcp"
          ]
        }
      }
    }
    ```

    3. Restart Claude Desktop. The Loop server appears in the **Connectors** list.
    4. Click **Connect** next to **loop-returns**. A browser window opens to Loop's OAuth flow — sign in with your Loop credentials and approve access.
  </Tab>

  <Tab title="Claude organization connector">
    Claude Team and Enterprise admins can add Loop as a custom organization connector instead of asking every user to edit their local Desktop config.

    1. In Claude, open **Organization Settings → Connectors**.
    2. Create a custom connector for your organization.
    3. Use the Loop MCP endpoint as the connector URL:

    ```text theme={null}
    https://api.loopreturns.com/mcp
    ```

    4. Publish or enable the connector for the organization.

    Each user still authenticates with their own Loop credentials the first time they use the connector, and Loop enforces that user's existing Loop Admin permissions.
  </Tab>

  <Tab title="Cursor">
    1. Open **Cursor Settings → MCP**.
    2. Add a new server with:

    ```json theme={null}
    {
      "mcpServers": {
        "loop-returns": {
          "url": "https://api.loopreturns.com/mcp"
        }
      }
    }
    ```

    3. Cursor opens the OAuth flow in a browser. Sign in with your Loop credentials and approve access.
  </Tab>

  <Tab title="VS Code Copilot">
    1. Open **Settings → Copilot → MCP Servers**.
    2. Add the server:

    ```json theme={null}
    {
      "loop-returns": {
        "url": "https://api.loopreturns.com/mcp"
      }
    }
    ```

    3. Reload the window. When you first invoke a Loop tool, Copilot prompts you to authenticate. Sign in with your Loop credentials and approve access.
  </Tab>
</Tabs>

## Multi-shop accounts

If your email is associated with more than one Loop shop, the OAuth flow shows a shop selector after you sign in. Pick the shop you want to grant the assistant access to. You can disconnect and reconnect to switch shops.

If your MCP client supports multiple server entries, create one Loop server per shop and name each entry after the shop, for example `loop-returns-store-a` and `loop-returns-store-b`. Each entry runs the same endpoint but keeps its own OAuth connection, making it easier to choose the right shop before asking the assistant to act.

## Verify the connection

Once connected, ask the assistant:

> "What Loop shop am I connected to?"

The assistant should call the `get_shop_info` tool and respond with your shop's name and ID. For users who belong to more than one Loop shop, this confirms the assistant is scoped to the shop selected during OAuth before you ask it to inspect or change returns. If you see an error about authentication or permissions, see the [Authentication](/mcp/authentication) guide.

## Try a few prompts

```text theme={null}
Show me the most recent 5 returns flagged for review.
```

```text theme={null}
Get the timeline for return #1234 and summarize what happened.
```

```text theme={null}
List the active workflows in my shop.
```

## Rate limits

| Limit                             | Scope                  |
| --------------------------------- | ---------------------- |
| 600 tool calls per hour           | Per authenticated user |
| 100 OAuth authorizations per hour | Per IP                 |
| 100 token requests per hour       | Per IP                 |

If you hit a rate limit, the assistant will surface the error and back off automatically. Heavy programmatic workloads should use the [REST API](/api-reference/getting-started) instead.

## Disconnect

To revoke access, disconnect the Loop server in your MCP client and revoke the session in **Loop Admin → Settings → Developers** (coming soon — for now, contact support to revoke a session immediately).

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/mcp/authentication">
    Understand the OAuth flow and how shops are scoped to tokens.
  </Card>

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