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_status | What is configured and what is missing to go live, with the next step for each gap. | rules:read, integrations:read, company:read |
get_settings | Policy, markets, reasons, locations, item rules, portal design and email copy. | rules:read, company:read |
update_policy | Change return policy fields; only the fields sent change. | rules:read, rules:write |
update_market | Change one market by key; only the fields sent change. | rules:read, rules:write |
update_markets | Replace all markets: countries, window, fees, destination, return methods. | rules:write |
update_reasons | Replace the return reasons. | rules:write |
update_locations | Replace the places parcels are sent to. | rules:write |
update_item_rules | Replace the rules for products that cannot be returned or need a notice. | rules:write |
update_messages | Replace the customer email copy overrides. | rules:write |
update_portal_design | Set the returns portal's look. | company:write |
suggest_portal_design_from_url | Suggest a portal design from the shop's own page. Not saved. | company:write |
detect_onsite_placement | Find where the on-site overlay goes on a product page. Not saved. | integrations:write |
list_integrations | Providers with their fields, and connected integrations with credentials masked. | integrations:read |
credentials_link | The admin page where the merchant enters an integration's keys. Keys are never taken in chat. | integrations:read |
test_integration | Check a saved integration against the provider. | integrations:write |
connect_integration | Change a saved integration's settings. Keys go in through credentials_link. | integrations:write |
list_returns | Returns, newest first, filtered by status, search, parcel issue or claims. | returns:read |
get_return | One return in full, with the status moves allowed now. | returns:read |
update_return_status | Move a return on or record its refund status, with a note. | returns:write |
create_return_link | A portal link for one order, for a customer service reply. | returns:write |
extend_return_window | Let one order be returned later than its normal window, or clear that. | returns:write |
create_test_order | A test order of real products in your name, with a portal link to try a return on it. | returns:write |
return_reason_analytics | Return reasons by product, brand and category. | returns:read |
faq_questions | What customers ask the portal's FAQ chat, and what the policy did not answer. | returns:read |
returns_terms_brief | Your 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_terms | Where a terms text disagrees with your settings. | rules:write |
klaviyo_flow_guide | How 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_message | Send 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.