MCP Server Integration with Recommend

Overview

The Recommend MCP (Model Context Protocol) server enables AI-powered shopping assistants to interact with Algonomy Recommend. It provides an MCP-compliant interface that allows LLMs to retrieve personalized product recommendations and shopper affinity information during conversational shopping experiences.

Built using the FastMCP framework, the server implements the Model Context Protocol (MCP), allowing seamless integration with MCP-compatible clients. These clients include off-the-shelf applications such as Claude Desktop and ChatGPT plugins, as well as custom-built shopping assistants and chatbot applications.

Instead of interacting directly with the underlying Recommend APIs, client applications invoke MCP tools exposed by the server. The MCP server manages the communication with Algonomy Recommend APIs and returns structured responses that the LLM can use to generate personalized shopping experiences.

This section is intended for:

  • Developers integrating the Recommend MCP server with AI-powered shopping assistants or custom chatbot applications.
  • Customer Success team responsible for configuring the ADA Recommend portal for MCP-based integrations.
  • Solution engineers implementing or supporting Recommend MCP deployments.

MCP Tools

The Recommend MCP server exposes two tools that enable an MCP-compatible client to retrieve personalized recommendations and shopper affinity information during a shopping conversation.

get_product_recommendations

The get_product_recommendations tool calls the ADA recsForPlacements API and returns a ranked list of recommended products for a shopper based on the specified intent.

The MCP server internally resolves the appropriate placement name from the supplied intent value. Placement names are never exposed to the LLM.

When to Use

Call this tool whenever the shopper's conversation indicates that product recommendations are required. Typical scenarios include:

  • Browsing products within a category.
  • Looking for similar products.
  • Requesting complementary products.
  • Comparing products.
  • Viewing previously viewed, purchased, wishlist, or cart items.

Required Parameters

  • apiKey
  • apiClientKey
  • sessionId
  • intent

Conditional Parameters

  • productId for product-based intents.
  • categoryId for discovery:category.
  • brand for discovery:brand.

Optional Parameters

  • userId
  • rcs
  • region
  • lang

get_affinity_scores

The get_affinity_scores tool calls the ADA affinityScoresByConfig API and returns a shopper's behavioral affinity profile. The response includes affinity scores for brands, categories, and product attributes calculated from shopper interactions such as product views, purchases, cart additions, and wishlist activity.

When to Use

Invoke this tool once at the beginning of a shopping session before the shopper sends the first message. This provides the LLM with shopper preferences so it can personalize the conversation from the outset.

Required Parameters

  • apiKey
  • apiClientKey
  • sessionId

Optional Parameters

  • userId
  • rcs
  • affinityConfigName (defaults to default).

Note: The get_affinity_scores tool returns shopper affinity information only. To retrieve product recommendations, use get_product_recommendations.

Intent Reference

The intent parameter supplied to the get_product_recommendations tool determines which recommendation model the MCP server invokes. The server internally maps each intent to its corresponding placement name, so placement names are never exposed to the LLM.

Intent What It Returns Seed Required
discovery:general Discovery recommendations with no specific context, based on shopper history and popularity. None
discovery:category Top products within a specific category, personalized to the shopper. categoryId
discovery:brand Top products from a specific brand, personalized to the shopper. brand
product:similar Products similar to the product currently being viewed. productId
product:cross_sell Complementary products that pair well with the viewed product. productId
product:comparison Products selected by the recommendation engine for comparison with the viewed product. productId
product:compare_selected Complete product attribute data for products that have already been selected for comparison. productId (pipe-separated list containing two or more product IDs, for example uv2345|xt1234)
user:viewed Products the shopper has recently viewed. None
user:purchased Products the shopper has previously purchased. None
user:wishlist Products saved to the shopper's wishlist. None
user:cart Products currently in the shopper's cart. None

Comparison Intents

The MCP server supports two intents for product comparison. Select the appropriate intent based on whether the comparison products have already been identified.

  • product:comparison: Use product:comparison when the shopper has selected a single product and wants to compare it with similar alternatives. The recommendation engine automatically determines the most appropriate products to compare against the selected product.
  • product:compare_selected: Use product:compare_selected when the shopper or the LLM has already selected two or more specific products for comparison. The tool returns complete attribute information for the selected products, enabling the LLM to generate a detailed comparison table.

Note: The MCP server resolves the placement corresponding to each intent internally. Client applications and LLMs only need to specify the appropriate intent value when invoking the get_product_recommendations tool.

Integration

The Recommend MCP server can be integrated with any MCP-compatible client. Depending on the client implementation, integration is performed either through native MCP support or by implementing the MCP client protocol in a custom application.

Connecting a Client to the MCP Server

There are two supported integration approaches for connecting a client to the Recommend MCP server.

Off-the-Shelf MCP Clients

Clients that provide native MCP support, such as Claude Desktop, ChatGPT plugins, and MCP-compatible frameworks like LangChain, can connect directly to the Recommend MCP server.

Register the MCP server URL using the client's plugin or server configuration settings. The client automatically performs the following tasks:

  • Discovers available tools by calling the tools/list endpoint.
  • Retrieves tool schemas.
  • Executes tool calls.
  • Returns tool responses to the LLM.

Custom Chatbot Applications

Applications that implement their own chatbot experience must implement the MCP client workflow. The application is responsible for communicating with the MCP server and coordinating tool execution with the LLM.

A custom MCP client should perform the following:

  1. Connect to the Recommend MCP server.
  2. Call the tools/list endpoint during application startup to discover available tools.
  3. Provide the retrieved tool schemas to the LLM.
  4. Detect tool invocation requests generated by the LLM.
  5. Call the appropriate MCP tool using the tools/call endpoint.
  6. Return the tool response to the LLM.
  7. Continue the conversation using the tool results.

Integration Workflow

The following high-level workflow describes how a typical MCP-compatible client interacts with the Recommend MCP server during a shopping session.

  1. Initialize the shopping session.
  2. Discover available MCP tools using the tools/list endpoint.
  3. Provide tool definitions to the LLM.
  4. Receive a shopper message.
  5. Determine whether a tool invocation is required.
  6. Invoke the appropriate MCP tool.
  7. Return the tool response to the LLM.
  8. Generate a personalized response for the shopper.
  9. Repeat the process for subsequent shopper interactions.

Note: The MCP server is stateless. The calling application is responsible for maintaining session context, supplying required parameters for every tool invocation, and preserving conversation state throughout the shopping session.

Session Initialization

Before invoking any MCP tool, the calling application must initialize the shopper session by providing the required session information. The Recommend MCP server does not generate, store, or resolve these values. They must be supplied by the client application for every shopping session.

Required Session Parameters

Provide the following parameters when initializing a shopping session:

  • apiKey – The ADA API key associated with the retailer site.
  • apiClientKey – The ADA API client key that identifies the client application or channel.
  • sessionId – A unique identifier for the shopper's current session.

These values should be injected into the LLM's context (for example, through a system prompt) so that they are included automatically in every MCP tool invocation.

Note: The Recommend MCP server does not retain session information between requests. The calling application must include the required session parameters with every tool call.

Authenticated Shoppers

If the shopper is authenticated, provide the userId parameter in addition to the required session parameters. Supplying the user identifier enables the recommendation engine to use historical shopper activity for improved personalization.

If the shopper is anonymous, omit the userId parameter. Recommendations are then generated using the current session context.

rcs Session Tracking Token

Every response returned by the Recommend APIs includes an rcs session tracking token. The client application is responsible for preserving this token throughout the shopping session.

When invoking the next MCP tool:

  • Store the rcs value returned in the previous response.
  • Pass the stored rcs value in the next tool request.
  • If the response contains a new rcs value, replace the previously stored value.
  • For the first tool invocation, omit the rcs parameter or pass an empty value.

IMPORTANT: Failing to pass the latest rcs value between tool invocations breaks personalization continuity and session tracking.

Session Management Best Practices

  • Generate a unique sessionId for each shopper session.
  • Reuse the same sessionId throughout the session.
  • Preserve and update the rcs value after every API response.
  • Include userId whenever the shopper is authenticated.
  • Ensure that all required session parameters are supplied with every MCP tool invocation.

FastMCP Call Structure

The Recommend MCP server is built using FastMCP. FastMCP wraps the parameters for each tool inside a named object before invoking the tool.

When an LLM or client application calls an MCP tool, the request parameters must be nested inside the appropriate wrapper object.

Parameter Wrappers

MCP Tool Wrapper Object
get_product_recommendations recsParam
get_affinity_scores affinityParam

Native MCP Clients

LLM clients that support native MCP tool invocation, such as OpenAI and Anthropic clients, automatically retrieve the tool schema from the tools/list endpoint and construct the required wrapper object. No additional implementation is required.

Note: When using native MCP-compatible clients, parameter wrapping is handled automatically based on the tool schema returned by the MCP server.

Custom MCP Integrations

Applications that invoke MCP tools programmatically must explicitly wrap the request parameters inside the appropriate wrapper object before calling the tool.

For example, requests to get_product_recommendations must place all parameters inside the recsParam object.

Example Request Structure

The following example shows the request structure for the get_product_recommendations tool.

{ "recsParam": { "apiKey": "your-api-key", "apiClientKey": "your-api-client-key", "sessionId": "abc123", "intent": "product:similar", "productId": "uv2345", "rcs": "current-rcs-value" } }

IMPORTANT: Requests that do not use the required wrapper object are not valid FastMCP tool requests and cannot be processed by the MCP server.

Best Practices

  • Use the wrapper object defined for the selected MCP tool.
  • Allow native MCP clients to construct the wrapper automatically whenever possible.
  • For custom integrations, ensure that all tool parameters are nested within the correct wrapper object.
  • Validate the request structure before invoking the MCP tool.

Click Tracking

When displaying recommended products, the client application must record shopper interactions with each recommended product. Click tracking provides the recommendation engine with engagement data that is used for reporting and improving future recommendations.

Each recommended product returned by the get_product_recommendations tool includes two fields that can be used for click tracking.

clickURL

The clickURL field contains a tracking URL that records the shopper's click and then redirects the shopper to the product page.

Use clickURL as the hyperlink (href) when the shopper navigates directly to the product details page by selecting a recommended product.

clickTrackingURL

The clickTrackingURL field records the shopper interaction without performing a redirect.

Use clickTrackingURL when the application navigates to the product page using productURL or another application-specific navigation mechanism. The tracking URL should be invoked in the background before or during navigation.

Choosing the Appropriate Tracking Method

Scenario Recommended Field
Navigate using the tracking link clickURL
Navigate using productURL or custom application routing clickTrackingURL

IMPORTANT: Use either clickURL or clickTrackingURL for every shopper interaction with a recommended product. Failing to record clicks results in incomplete engagement data and reporting.

Best Practices

  • Record every shopper interaction with recommended products.
  • Use clickURL when redirect-based navigation is acceptable.
  • Use clickTrackingURL when the application controls navigation through productURL or custom routing.
  • Ensure that only one tracking mechanism is used for each product interaction.
  • Preserve click tracking throughout the shopper session to maintain accurate recommendation analytics.

Portal Configuration

Before the Recommend MCP server can be used, the required recommendation placements and strategies must be configured in the ADA portal. This configuration is typically performed by the Customer Success Architect (CSA) in collaboration with the retailer.

The MCP server depends on these portal configurations to resolve shopper intents to the appropriate recommendation models. Without the required placements and strategy rules, the MCP server cannot retrieve recommendations for supported intents.

Configuration Requirements

Before deploying the Recommend MCP server, complete the following portal configuration tasks:

  • Create the required recommendation placements.
  • Create any configurable recommendation strategies referenced by the placement rules.
  • Assign the appropriate strategies to each placement.
  • Activate the placement rules in both the Integration and Production environments.
  • Configure the placement rules with an Evergreen end date.

Note: Portal configuration is primarily the responsibility of the Customer Success Architect (CSA) working with the retailer.

Portal Configuration Components

The Recommend MCP server requires the following configuration components in the ADA portal:

  • Placements – Map shopper intents to recommendation models.
  • Configurable Strategies – Define recommendation strategies that must be created before they can be referenced by placement rules.
  • Strategy Rules – Associate recommendation strategies with placements and control recommendation behavior.

IMPORTANT: Placement names must exactly match the names expected by the Recommend MCP server. The server resolves recommendation models using these predefined placement names.

Configuration Workflow

  1. Create the required placements.
  2. Create any configurable recommendation strategies.
  3. Assign strategies to their corresponding placements.
  4. Activate the strategy rules.
  5. Verify the configuration in the Integration environment.
  6. Promote the configuration to the Production environment.

The following sections describe the required placements, configurable strategies, and strategy rules in detail.

Placements

Create one placement for each supported recommendation intent. The placement names must match the values expected by the Recommend MCP server exactly. The MCP server uses these placement names internally to resolve the recommendation model associated with each intent.

IMPORTANT: Do not modify the placement names shown below. The Recommend MCP server relies on these predefined names to map intents to recommendation models.

Intent Placement Name
discovery:general home_page.mcp_discovery_general
discovery:category category_page.mcp_discovery_category
discovery:brand brand_page.mcp_discovery_brand
product:similar item_page.mcp_product_similar
product:cross_sell item_page.mcp_product_cross_sell
product:comparison item_page.mcp_product_comparison
product:compare_selected home_page.mcp_product_compare_selected
user:viewed home_page.mcp_user_viewed
user:purchased home_page.mcp_user_purchased
user:wishlist home_page.mcp_user_wishlist
user:cart home_page.mcp_user_cart

Placement Guidelines

  • Create one placement for every supported recommendation intent.
  • Ensure that each placement name exactly matches the value expected by the Recommend MCP server.
  • Configure the corresponding recommendation strategies for each placement before activating the placement.
  • Verify the placement configuration in the Integration environment before promoting it to Production.

Note: The LLM never references placement names directly. Client applications specify only the intent parameter, and the Recommend MCP server internally maps the intent to the corresponding placement.

Configurable Strategies

The following recommendation strategies must be created in the ADA portal before they are referenced by the placement rules. All other strategies used by the MCP server are legacy strategies and do not require additional configuration.

Note: Only the strategies listed below require manual creation in the ADA portal. All other strategies referenced by the placement rules are legacy strategies that are already available.

Strategy Name Strategy Message Model Type Model Additional Settings
ComparisonStrategy Compare with similar products Product to Product Viewed Together or Similar Products
  • Personalization Seed: Product Context
  • Include seed product in results.
UserCart Currently in your cart User's Activity User's Cart None
UserPurchaseHistory Your previous purchases User's Activity User Purchase History Personalization Sort: Recency
UserWishlist Your wishlist items User's Activity User Wishlist None

Configuration Guidelines

  • Create each configurable strategy before configuring the corresponding placement rules.
  • Ensure that the strategy name matches the expected value exactly.
  • Configure the specified recommendation model and additional settings for each strategy.
  • After creating the strategies, assign them to the appropriate placement rules as described in the next section.

IMPORTANT: The ComparisonStrategy must use the Viewed Together or Similar Products model with the Product Context personalization seed enabled, and the seed product must be included in the recommendation results.

After creating the configurable strategies, configure the placement-specific strategy rules described in the Strategy Rules per Placement section.

Strategy Rules per Placement

After creating the required placements and configurable strategies, configure the strategy rules for each placement. These rules determine which recommendation strategies are executed for each shopper intent.

Activate all strategy rules in both the Integration and Production environments, and configure an Evergreen end date.

IMPORTANT: Ensure that all strategy rules are active in both Integration and Production environments with an Evergreen end date before deploying the Recommend MCP server.

Placement Strategies Notes
home_page.mcp_discovery_general

PersonalizedClickCP

MultiItemPersonalizedViewCP

ReplenishmentInPurchasedProductsStrategy

Enable backfill.
category_page.mcp_discovery_category

PersonalizedClickCPInCategory

PersonalizedViewedPurchaseInCategory

Enable backfill.
brand_page.mcp_discovery_brand

BrandPopularProducts

BrandTopProducts

BrandTopSellers

None.
item_page.mcp_product_similar

ClickCP

SimilarProducts

ViewedPurchased

CategorySiloedViewCP

CategorySiloedViewPurchaseCP

Enable backfill.
item_page.mcp_product_cross_sell

PurchaseCP

SessionPurchaseCP

RelatedToCartViewCPFiltered

RelatedToCartCategoryFiltered

Enable backfill.
item_page.mcp_product_comparison

ComparisonStrategy

Enable Use Only These.
home_page.mcp_product_compare_selected

EchoProducts

Enable Use Only These.
home_page.mcp_user_viewed

RecentHistoricalItems

Enable Use Only These.
home_page.mcp_user_purchased

UserPurchaseHistory

Enable Use Only These.
home_page.mcp_user_wishlist

UserWishlist

Enable Use Only These.
home_page.mcp_user_cart

UserCart

None.

Configuration Guidelines

  • Assign the specified strategies to each placement.
  • Configure all placement rules in both the Integration and Production environments.
  • Use an Evergreen end date for all rules.
  • Enable Backfill or Use Only These where specified.
  • Verify the configuration before making the MCP server available to client applications.

Note: Strategies such as UserPurchaseHistory, UserWishlist, UserCart, and ComparisonStrategy must be created before they can be assigned to the corresponding placement rules.