MCP server

Claude, ChatGPT, Cursor and other assistants that speak the Model Context Protocol can set up and run Returnloop for you: markets, reasons, carriers, the portal's look, and day to day returns. Every tool does exactly what the same action in admin does, with the same checks.

Connect

URL: https://api.getreturnloop.com/mcp (Streamable HTTP)

Sign in (Claude, ChatGPT)

Add the URL as a custom connector. The assistant sends you to Returnloop: sign in, pick the company if you have several, and choose read only or full access. You can never give an assistant more than your own role allows, and if you lose access to the company the connection stops working. See and disconnect connected assistants in admin under Connections, AI assistants.

Claude (claude.ai and Claude Desktop)

Settings, Connectors, Add custom connector. Paste the URL, then sign in to Returnloop and approve.

https://api.getreturnloop.com/mcp

ChatGPT

Settings, Apps and Connectors, Create (developer mode). Paste the URL, choose OAuth, then sign in to Returnloop and approve.

https://api.getreturnloop.com/mcp

API key (Claude Code, Cursor, scripts)

Send Authorization: Bearer <your Returnloop API key>. Create the key in admin under Connections, API keys. Its scopes decide what the assistant may do: a key with only returns:read can look at returns but change nothing.

Claude Code

Run in a terminal.

claude mcp add --transport http returnloop https://api.getreturnloop.com/mcp --header "Authorization: Bearer <your Returnloop API key>"

Cursor

~/.cursor/mcp.json, or .cursor/mcp.json in a project.

{
  "mcpServers": {
    "returnloop": {
      "url": "https://api.getreturnloop.com/mcp",
      "headers": {
        "Authorization": "Bearer <your Returnloop API key>"
      }
    }
  }
}

OpenAI API and scripts

A tool in a Responses API request, or any MCP client that sends a header.

{
  "type": "mcp",
  "server_label": "returnloop",
  "server_url": "https://api.getreturnloop.com/mcp",
  "headers": {
    "Authorization": "Bearer <your Returnloop API key>"
  },
  "require_approval": "always"
}

Either way, a tool the connection is not allowed to use answers with the scope it needs. Credentials you give the assistant for carriers and other integrations are stored encrypted and only ever shown masked.

For client developers

OAuth 2.1 per the MCP authorization spec: /mcp answers 401 with a resource_metadata pointer (RFC 9728), authorization server metadata is at /.well-known/oauth-authorization-server (RFC 8414), clients register themselves (RFC 7591, public clients, https or loopback redirect URIs), and the code flow requires PKCE S256. Tokens are bound to https://api.getreturnloop.com/mcp (RFC 8707); access tokens last an hour and refresh tokens rotate on every use. Scopes: read and full.

Tools

Start with setup_status. Tools named update_ replace the whole list, so the assistant reads get_settings first and sends it back changed.

setup_statusWhat is configured and what is missing to go live, with the next step for each gap.rules:read, integrations:read, company:read
get_settingsPolicy, markets, reasons, locations, item rules, portal design and email copy.rules:read, company:read
update_policyChange return policy fields; only the fields sent change.rules:read, rules:write
update_marketChange one market by key; only the fields sent change.rules:read, rules:write
update_marketsReplace all markets: countries, window, fees, destination, return methods.rules:write
update_reasonsReplace the return reasons.rules:write
update_locationsReplace the places parcels are sent to.rules:write
update_item_rulesReplace the rules for products that cannot be returned or need a notice.rules:write
update_messagesReplace the customer email copy overrides.rules:write
update_portal_designSet the returns portal's look.company:write
suggest_portal_design_from_urlSuggest a portal design from the shop's own page. Not saved.company:write
detect_onsite_placementFind where the on-site overlay goes on a product page. Not saved.integrations:write
list_integrationsProviders with their fields, and connected integrations with credentials masked.integrations:read
credentials_linkThe admin page where the merchant enters an integration's keys. Keys are never taken in chat.integrations:read
test_integrationCheck a saved integration against the provider.integrations:write
connect_integrationChange a saved integration's settings. Keys go in through credentials_link.integrations:write
list_returnsReturns, newest first, filtered by status, search, parcel issue or claims.returns:read
get_returnOne return in full, with the status moves allowed now.returns:read
update_return_statusMove a return on or record its refund status, with a note.returns:write
create_return_linkA portal link for one order, for a customer service reply.returns:write
extend_return_windowLet one order be returned later than its normal window, or clear that.returns:write
create_test_orderA test order of real products in your name, with a portal link to try a return on it.returns:write
return_reason_analyticsReturn reasons by product, brand and category.returns:read
faq_questionsWhat customers ask the portal's FAQ chat, and what the policy did not answer.returns:read
returns_terms_briefYour settings as plain facts, your saved terms and your answers, for the assistant to rewrite your returns terms to match. Also as the prompt align_returns_terms.rules:read
check_returns_termsWhere a terms text disagrees with your settings.rules:write
klaviyo_flow_guideHow to build your Klaviyo flows and email for Returnloop's customer emails, with every event and an example. Also as the prompt build_klaviyo_flows.any
send_test_messageSend one customer email to Klaviyo as a test event, to your own address.rules:write

Klaviyo flows

Returnloop sends each customer email to your Klaviyo as an event, with every word already written in the customer's language. Your Klaviyo sends it through a flow per event. If your assistant also has Klaviyo's own MCP server connected, it can build those flows for you: run the prompt build_klaviyo_flows, or ask it to use klaviyo_flow_guide.

The guide is generated from the code that builds the events, so it always matches what is sent: every Klaviyo metric and the messages on it, when each is sent, every property with its type and an example event, the flow settings (Smart Sending off, transactional, test events), how to send a real test with send_test_message or create_test_order, and a checklist per flow. Returnloop never changes your Klaviyo itself.

The assistant starts from what you have: it reviews your existing flows and your best current emails, and any brand guidance it can reach (brand guidelines, tone of voice, a design system, your website), and reuses that header, footer, fonts, colours and tone so the return emails look like the rest of your mail. It falls back to a plain template only when nothing exists, asks before replacing anything live, and ends with a short report of what it found, reused and built, and what is left for you in Klaviyo. Where Klaviyo's API does not allow creating flows, the assistant creates the template and gives you the few clicks to finish in Klaviyo.