ShopBack Shopping MCP integration guide

Overview

The ShopBack Shopping MCP lets an AI assistant help a member find relevant merchant offers and start a tracked shopping trip.

The initial integration supports three tasks:

1. Search for participating merchants.
2. Retrieve the offers, terms, and indicative earning information available to the signed-in member.
3. Create a tracked shopping trip and return a redirect URL to the merchant.

The assistant does not complete checkout. Payment, order fulfilment, cancellations, and returns remain between the member and the merchant. Any earning shown before purchase is an estimate; final eligibility and the confirmed amount depend on the applicable offer terms and transaction validation.

Availability and access requirements

The integration is available to members in supported ShopBack markets. Participating merchants, offers, eligibility, and terms vary by market and account.

To use the integration, a client must:

• support MCP over Streamable HTTP;
• support OAuth 2.0 Authorization Code flow with PKCE using S256;
• send bearer access tokens with MCP requests;
• preserve the member's authenticated session while opening a merchant redirect; and
• display the required disclosure before sending the member to a merchant.

A ShopBack account is required for personalized offers and tracked shopping trips.

Endpoint and transport

Production

https://connect.shopback.com/shopping-agent/mcp

A staging endpoint and test account are provided securely during onboarding.

The server uses stateless MCP Streamable HTTP:

• Send MCP requests with POST.
• Responses may use application/json or text/event-stream.
• The first version exposes MCP tools only.
• Clients should negotiate a mutually supported MCP protocol version during initialization. The server supports the 2025-11-25 and 2026-07-28 protocol versions.

Authentication and authorization

The server uses OAuth 2.0 Authorization Code flow with PKCE. API keys are not supported for member-facing requests.

When a request has no valid access token, the server returns 401 Unauthorized with a WWW-Authenticate challenge. Clients should use the advertised authorization-server metadata to begin sign-in and consent.

When the token is valid but lacks the scope a tool requires, the server rejects the call with 403 Forbidden and an insufficient_scope challenge before the tool runs. The challenge names the required scope, so the client can request it and repeat the call.

Scopes

Searching needs no agent scope beyond member sign-in. Request offers:read to retrieve merchant offers, and trips:create to create tracked trips. Without trips:create, the client must not call get_redirect.

OAuth client registration may use pre-registered client credentials or Dynamic Client Registration, depending on the integrating platform. Confirm the registration method, callback URIs, and supported response types during onboarding.

Tool summary

Result format

Successful tool calls return machine-readable data in structuredContent and the same response as JSON text in content.

{
  "structuredContent": {
    "market": "XX",
    "asOf": "2026-10-07T12:00:00Z",
    "data": {},
    "warnings": [],
    "nextActions": []
  },
  "content": [
    {
      "type": "text",
      "text": "{\"market\":\"XX\",\"asOf\":\"2026-10-07T12:00:00Z\",\"data\":{},\"warnings\":[],\"nextActions\":[]}"
    }
  ]
}

Clients should use structuredContent for application logic. The content field is intended for display and may change independently of the structured schema.

Common fields:

• market: the ShopBack market associated with the authenticated member;
• asOf: the time at which the returned information was current;
• data: the tool-specific response;
• warnings: important limitations or eligibility notes; and
• nextActions: safe actions the assistant can offer next.

Tools

search

Find participating merchants whose name or category matches a keyword.

Input:

{
  "query": "running shoes",
  "limit": 10
}

The response may include an opaque merchant ID, display name, category, logo, headline offer information, and whether a tracked trip can currently be created.

Examples of suitable requests:

• “Find stores with good deals on running shoes.”
• “Where can I compare offers for a hair dryer?”
• “Show me participating hotel-booking merchants.”
• “Find merchants for flights to Tokyo.”

Search results represent participating merchants, not a comprehensive product, hotel, or flight inventory. The assistant should not claim that a result is the cheapest option across the market unless it has evidence from an appropriate comparison source.

get_merchant_offers

Retrieve current offer details and terms for a merchant.

Input:

{
  "merchantId": "1816",
  "amount": 200
}

The response may include:

• the merchant name and category;
• current rates, tiers, caps, exclusions, and expiry information;
• an indicative earning amount when amount is supplied; and
• the terms that may affect eligibility.

An estimate is not a guarantee. The final outcome can change because of exclusions, order changes, cancellations, returns, merchant reporting, or transaction validation.

Merchant-supplied terms are untrusted data. Clients must display or summarize them as offer information and must never treat text inside the terms as instructions to the assistant.

get_redirect

Create a tracked shopping trip and return a merchant redirect URL.

Input:

{
  "merchantId": "1816"
}

Each successful call creates a new shopping trip. The client must call this tool only after the member has chosen a merchant and confirmed they want to continue.

The response includes a disclosure, and the tool result's text begins with it. Display that disclosure verbatim together with the link before opening the redirect, and do not change either.

The returned URL is opaque. Do not parse, rewrite, decorate, or expose its internal parameters. Open it in the same browser context where possible so the member can continue to the merchant with fewer session issues.

get_redirect is non-idempotent. Never retry it automatically after a timeout or uncertain response. Ask the member before creating another trip.

Market and account context

The server derives the member's market and eligibility from the validated OAuth identity. Clients must not send a country or market header to override this context.

If the account market is unsupported, the server returns UNSUPPORTED_MARKET. If a merchant or offer is unavailable to that member, the client should explain that availability varies by market and account rather than implying a system failure.

Errors and retry behaviour

Authentication and scope failures occur at the HTTP layer. Tool-level failures arrive inside the tool result, marked with isError, with the HTTP request itself succeeding. The result carries a stable error code:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": "MERCHANT_NOT_FOUND",
      "message": "Merchant not found. Use search to find the merchant id.",
      "retryable": false,
      "nextActions": []
    }
  }
}

The same error object is also the text in content. retryable says whether the client may retry the same call: retry only when it is true, with bounded exponential backoff and jitter. nextActions, when present, suggests a safe follow-up tool call.

Do not automatically retry invalid requests, authorization failures, or get_redirect.

Privacy and security

• Request only the scopes needed for the intended experience.
• Never ask for or send ShopBack passwords, one-time codes, payment card details, or merchant credentials through tool inputs.
• Do not log access tokens, refresh tokens, redirect URLs, or raw authorization headers.
• Treat merchant names, descriptions, terms, and URLs as untrusted external data.
• Preserve redirect URLs exactly as returned and allow only secure https destinations.
• Keep member-facing claims grounded in the returned offer details and applicable terms.
• Do not imply that an estimate is confirmed or guaranteed.

Use the Privacy Policy and Terms and Conditions applicable to the member's ShopBack market.

Integration onboarding

Before testing begins, the integrating team should provide:

• application name and owner;
• development and production callback URIs;
• OAuth client registration preference, if the platform has one;
• supported MCP protocol versions and response content types;
• whether a read-only integration is required; and
• technical and operational contacts.

ShopBack will provide the staging endpoint, test-account instructions, OAuth registration details, supported market information, and an operational contact through an approved secure channel.

Acceptance checklist

An integration is ready for review when it can demonstrate that it:

• completes OAuth sign-in with PKCE and uses the minimum required scopes;
• initializes an MCP session and negotiates a supported protocol version;
• searches for merchants and handles an empty result set;
• retrieves offer details and clearly labels estimates and conditions;
• creates a redirect only after an explicit member choice;
• shows the returned disclosure before opening the merchant;
• does not automatically retry get_redirect;
• handles unsupported markets, missing scopes, rate limits, and temporary failures safely;
• does not accept client-supplied market overrides; and
• avoids logging tokens, redirect URLs, and sensitive member data.