Get started

This guide explains how to connect to and use the Loomi Connect MCP server in various environments, along with sample custom client implementations.

Prerequisites

To connect to the Loomi Connect MCP server, make sure you have:

• Bloomreach Discovery account: An active Discovery subscription with the Search module.

• Bloomreach MCP key: Request an MCP key by contacting your account representative.

• Development environment: Preferred development environment for client implementation (Node.js, Python, TypeScript).

• LLM environment: Access to an LLM environment with support for MCP tools (Cursor, OpenAI Playground).

Choose your integration environment

Loomi Connect MCP supports integration with various LLMs and environments. The integration paths serve different use cases and development workflows. Choose the integration path that suits your needs and workflow.

• The Client implementation path lets you build custom applications and agents by implementing your own MCP client, giving you complete control over the integration and functionality.

• The Cursor IDE integration enables developers to access Bloomreach Discovery data directly within their code editor, streamlining development workflows and enabling AI-assisted coding with real commerce data context.

• The OpenAI Playground option provides a no-code way to experiment with MCP capabilities, allowing you to test prompts and interactions with OpenAI models while connected to your Discovery instance—ideal for prototyping and validation before full implementation.

Example MCP server request

The MCP server uses the Discovery Product and Category Search API to fetch your catalog data. It connects to clients over HTTP/SSE. Given below are example cURL requests to the search functionality endpoint of the server using path-based and header-based authentication methods.

See technical specifications for details on authentication and other supported parameters.

curl -s -X POST https://mcp.bloomreach.com/1234/documentation_site/${YOUR_MCP_KEY}/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0",
    "id":"search-1",
    "method":"tools/call",
    "params":{
      "name":"search",
      "arguments":{"params":{"q":"red","facet":"true","rows":24}}
    }
  }'

curl -s -X POST https://mcp.bloomreach.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'account_id: 1234' \
  -H 'domain_key: documentation_site' \
  -H 'x-api-key: ${YOUR_MCP_KEY}' \
  -d '{
    "jsonrpc":"2.0",
    "id":"search-1",
    "method":"tools/call",
    "params":{
      "name":"search",
      "arguments":{"params":{"q":"red","facet":"true","rows":24}}
    }
  }'

This example shows a basic product search for 'red' items. Use this to verify your API credentials work before building a full integration.

The server returns product results in the same format as the Discovery Search API. If this works, you're ready to connect an AI application.

Client implementations

To connect with the MCP server in your development environment, implement a client that handles MCP calls within your custom agent or project.

Bloomreach provides sample clients for Node.js, Python, and TypeScript to accelerate your integration. These reference implementations demonstrate the requirements and best practices for custom client development, streamlining the process of incorporating the MCP server into your LLM applications.

Use the sample implementations as a template to start building your own custom clients.

📘

Note

Refer to the README.md file of each sample client in GitHub for instructions on its setup and usage.

After setting up a client by following the README file, you can make test calls to the MCP server with desired parameter values from the terminal.

npm run start -- --q "shirt" --rows 12 --facet

python client/python/mcp_client.py --q "shirt" --rows 12 --facet

npm run build && npm run start -- \
  --q "chair" \
  --arg fq=category:living \
  --arg fq=color:black \
  --arg fl=url,pid,title,price

Use the MCP server in Cursor

Install Loomi Connect MCP in Cursor as an MCP tool to use it as a Context source inside the IDE.

Configure the MCP tool

Configure the MCP tool in Cursor's mcp.json config file. You can set it up globally (for all projects) or for a specific project.

Example configuration

Pass your authentication credentials in the configuration as headers or path parameters in the server URL. 

The path-based configuration uses the following URL format: https://mcp.bloomreach.com/<account_id>/<domain_key>/<x-api-key>/mcp

{
  "mcpServers": {
    "bloomreach-discovery-mcp": {
      "type": "http",
      "url": "https://mcp.bloomreach.com/1234/documentation_site/<YOUR_MCP_KEY>/mcp"
    }
  }
}

{
  "mcpServers": {
    "bloomreach-discovery-mcp": {
      "type": "http",
      "url": "https://mcp.bloomreach.com/mcp",
      "headers": {
        "account_id": "1234",
        "domain_key": "documentation_site",
        "x-api-key": "<YOUR_MCP_KEY>"
      }
    }
  }
}

Alternatively, you can configure the authentication credential values as environment variables for additional security.

📘

Note

Refer to the Cursor documentation to learn more about installing custom MCP servers.

Use the tool in chat

Your agent automatically decides to use the configured MCP tool when applicable in a conversation. The bloomreach-discovery-mcp tool should be listed under your Available tools, which can be used to toggle it on. 

The agent asks for approval before using the MCP tool by default. If you enable auto-run for the agent, it uses the MCP tool without asking for permission.

Use the MCP server in OpenAI Playground

Loomi Connect MCP can be configured in OpenAI Playground in the Chat or Agent Builder modes.

Follow the steps given below to configure the MCP tool:

1. Click + Add in the Tools section.

2. Choose the MCP server hosted tool option.

3. In the Add MCP server modal, click + Server to configure the Loomi Connect MCP server.

   

4. Configure the MCP server using the following settings:

   
   1. URL: https://mcp.bloomreach.com/mcp
   2. Label: discovery_mcp (or any other identifier for the tool)
   3. Choose Custom headers as theAuthentication method, and add the account_id, domain_key, and x-api-key headers with the correct values for your Bloomreach Discovery account.

5. Click Connect.

6. The tool is now available to the LLM and is called automatically when applicable in a conversation.

Technical specifications

The MCP server acts as a communication interface between AI applications and your Bloomreach Discovery instance. It allows LLMs to retrieve product information or execute searches without complex API integrations. 

The following sections highlight the key specifications of the service.

Authentication

To connect your AI application to Discovery, you'll need to pass three authentication credentials in the headers or as path parameters. These specify which Bloomreach account and catalog the MCP server should access.

The MCP server supports the following Discovery API parameters in the headers or as path parameters, allowing for flexible and reliable authentication.

Find the values for account_id and domain_key in your Bloomreach dashboard under the API details. The x-api-key is your Bloomreach MCP key (contact your account representative for a new key if you don't have one already).

You must include these in your MCP configuration when setting up the connection.

Supported API parameters

The Loomi Connect MCP service supports the functionality provided by the following API parameters of the Discovery Product and Category Search API:

📘

Note

Refer to the Discovery Product and Category Search API reference to know more about each API parameter’s functionality and usage.

These parameters can be used to refine the Discovery API call to return more accurate and relevant results for the user’s natural language query.

🚧

Warning

The capabilities of the MCP service depend on your Bloomreach Discovery package, and the active features. If a feature supported by the MCP server isn't active in your Discovery account, it won't work through the MCP layer.