Sales Layer MCP Server

Connect your Sales Layer catalog to AI assistants like Claude and ChatGPT

📚 Installation Guides

Choose your language:

• 🇬🇧 English Installation Guide
• 🇪🇸 Guía de Instalación en Español
• 🇪🇸 Guia d'Instal·lació en Català
• ⚡ Quick Start Guide

For developers:

• 🔧 Development & Maintenance Guide

What is this?

The Sales Layer MCP Server allows you to connect your Sales Layer product catalog to AI assistants using the Model Context Protocol (MCP). Ask questions about your products, categories, and variants in natural language.

Supported AI assistants:

• Claude Web (claude.ai)
• ChatGPT (chatgpt.com)
• Claude Desktop
• Google AI Studio
• Other MCP-compatible tools

Quick Start

Remote Server (Recommended)

URL: https://mcp.saleslayer.com

1. Get your Catalog Token from Sales Layer
2. Add the connector in your AI assistant (see installation guides above)
3. Authenticate with your token
4. Start asking questions!

Local Installation

Option 1: NPM Package (Recommended)

npm install -g @saleslayer/mcp-server

Option 2: Claude Desktop Extension Packages

Download pre-built packages for Claude Desktop:

• OnlyRead (read-only access):
  • DXT format
  • MCPB format
• Full (read and write access):
  • DXT format
  • MCPB format

See the installation guides for detailed setup instructions.

What's New in v1.2.0

• ✅ Multi-client support: Claude Web, ChatGPT, Claude Desktop, and more
• ✅ OAuth 2.0 with PKCE: Secure authentication flow
• ✅ Dynamic Client Registration (RFC 7591): Automatic client setup
• ✅ Unified URL: Single base URL for all clients
• ✅ Profile-based access: OnlyRead and Full access levels
• ✅ Token encryption: AES-256-GCM encryption for stored tokens
• ✅ Refresh token rotation: Enhanced security
• ✅ Comprehensive logging: Debug and audit capabilities

Quick Start (Local)

Run remote server (single port)

# Both profiles served on port 8001 (OnlyRead and Full)
$env:PORT="8001"; node bin/server-remote-both.js

Endpoints:

• http://localhost:8001/onlyread/mcp
• http://localhost:8001/full/mcp

Example request (PowerShell):

$headers = @{ Authorization = "Bearer YOUR_CATALOG_TOKEN" }
$body = @{ jsonrpc="2.0"; id="1"; method="tools/list"; params=@{} } | ConvertTo-Json -Compress
Invoke-RestMethod -Uri http://localhost:8002/full/mcp -Method POST -Headers $headers -ContentType 'application/json' -Body $body

Claude integration (Remote OAuth)

The server implements MCP's standard OAuth flow. Claude opens the "Authorize" UI where you enter your Catalog Token once; you do not set it in .env or in Claude Desktop.

• Discovery: GET /.well-known/oauth-authorization-server
• Authorize UI: GET/POST /oauth/authorize
• Token: POST /oauth/token (authorization_code and refresh with rotation)
• Revoke: POST /oauth/revoke
• DCR: POST /oauth/register

See docs/plan_oauth_mcp_saleslayer.md for detailed flows.

Security (CORS/Hosts)

Environment variables to harden deployments:

• CORS_ORIGINS: comma-separated allowed origins (e.g., https://claude.ai)
• ALLOWED_HOSTS: allowed values for the Host header (e.g., mcp.saleslayer.com)
• ALLOWED_ORIGINS: additional origin allowlist (e.g., https://claude.ai)
• ENABLE_DNS_REBINDING_PROTECTION=true (recommended)
• FORCE_HTTPS=true (default)

Docker

• Dockerfile multi-stage listo.
• docker-compose.yml expone:
  • onlyread en 8001
  • full en 8002

# Local (WSL)
docker compose -f docker-compose.local.yml up -d --build

# QA (reverse proxy exposes 443 only)
docker compose -f docker-compose.qa.yml --env-file .env.qa up -d --build

# Production (reverse proxy exposes 443 only)
docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --build

External URLs (behind reverse proxy):

• Readonly: https://mcp.saleslayer.com/readonly
• Full: https://mcp.saleslayer.com/full
• OAuth UI: https://mcp.saleslayer.com/oauth/authorize

Internal app endpoints (for reference):

• /onlyread/mcp, /full/mcp

Local (stdio) configuration for Claude Desktop

To run the stdio server with NPX in Claude Desktop (local mode):

{
  "mcpServers": {
    "sales-layer": {
      "command": "npx",
      "args": ["--yes", "@saleslayer/mcp-server@latest"],
      "env": { "CATALOG_TOKEN": "your_token" }
    }
  }
}

Restart Claude Desktop after editing its configuration.

🔑 Getting Your Catalog Token

1. Log into your Sales Layer admin panel
2. Navigate to API/Tokens section
3. Copy your catalog API token
4. Use this token in the configuration above

🛠️ Available Tools

Once configured, Claude can help you with:

Catalog Management

• Search products: Find products by name, category, or attributes
• Browse categories: Explore your product category structure
• Get product details: Retrieve detailed product information
• Search variants: Find specific product variants

Data Queries

• Filter products: Use advanced filters (status, price, category)
• Get metadata: Understand your catalog structure
• Custom entities: Access custom data entities
• Validate access: Check token permissions

💬 Example Conversations

Search for products:

"Show me all electronics products under $100"

Category exploration:

"What categories do we have in our catalog?"

Product details:

"Get details for product SKU ABC123"

Advanced filtering:

"Find all visible products in the 'clothing' category with prices between $20 and $50"

Metadata exploration:

"What fields are available for products in our catalog?"

Multilingual searches:

"Find products with 'Abrigo' in the title" "Search for 'Winter Coat' in English or 'Abrigo de Invierno' in Spanish" "Show me all products with 'Chaqueta' in any language"

🌍 Multilingual Catalog Support

The MCP server provides intelligent multilingual search capabilities:

Automatic Language Detection: Claude can detect the language of your search terms and automatically search in the appropriate language fields.

Example workflows:

• You ask: "Find products with 'Abrigo'"
• Claude detects Spanish → Searches in prod_title_es
• If no results → Also searches in default language

Multiple Language Search:

• You ask: "Find 'Coat' or 'Abrigo'"
• Claude searches: prod_title_en OR prod_title_es

Get Help:

"How do I search in multiple languages?" "What languages are available in my catalog?"

The server will guide you through multilingual search strategies automatically.

🔧 Troubleshooting

Common Issues

"MCP server not found"

• Ensure Node.js 18+ is installed: node --version
• Check internet connection (NPX downloads the package)
• Restart Claude Desktop after configuration

"Invalid token" errors

• Verify your catalog token is correct
• Check token permissions in Sales Layer admin
• Ensure token hasn't expired

"No results found"

• Check your catalog has visible products
• Verify product status filters
• Try broader search terms
• For multilingual catalogs: Make sure you're searching in the right language field

Multilingual search issues

• Use language-specific fields: prod_title_es, prod_title_en, etc.
• Ask Claude: "How do I search in multiple languages?"
• Use the help tool: "help_search_multilingual"
• Check available languages: "What languages are in my catalog?"

Debug Mode

Enable debug logging by adding to your configuration:

{
  "mcpServers": {
    "sales-layer": {
      "command": "npx",
      "args": ["--yes", "@saleslayer/mcp-server@latest"],
      "env": {
        "CATALOG_TOKEN": "your_token",
        "DEBUG": "true",
        "LOG_TO_FILE": "true"
      }
    }
  }
}

Cache Configuration

Configure intelligent caching for better performance:

{
  "mcpServers": {
    "sales-layer": {
      "command": "npx",
      "args": ["--yes", "@saleslayer/mcp-server@latest"],
      "env": {
        "CATALOG_TOKEN": "your_token",
        "CACHE_ENABLED": "true",
        "CACHE_TABLES_TTL": "300000",
        "CACHE_METADATA_TTL": "600000"
      }
    }
  }
}

Cache Settings:

• CACHE_ENABLED: Enable/disable caching (default: true)
• CACHE_TABLES_TTL: Cache duration for all tables in milliseconds (default: 300000 = 5 minutes)
• CACHE_METADATA_TTL: Cache duration for metadata in milliseconds (default: 600000 = 10 minutes)

Cache Features:

• ✅ Automatic invalidation on data changes (CREATE/UPDATE/DELETE)
• ✅ Smart relationship-based invalidation
• ✅ Configurable TTL per data type
• ✅ Performance metrics and monitoring
• ✅ Manual cache control via MCP tools

Getting Help

1. Check Claude Desktop logs for error messages
2. Verify token permissions in Sales Layer admin
3. Test API access directly in Sales Layer
4. Contact Sales Layer support for token issues

📋 System Requirements

• Node.js 18.0.0+ (LTS recommended)
• Claude Desktop (latest version)
• Sales Layer account with API access
• Internet connection for package downloads

🔒 Security & Privacy

• Your catalog token is stored locally in Claude Desktop configuration
• No .env files needed - tokens are passed securely via Claude Desktop
• No data is sent to third parties
• All API calls go directly to Sales Layer servers
• Token is transmitted securely via HTTPS

🏗️ Development

Local Development

# Clone the repository
git clone <repository-url>
cd saleslayer-mcp-server

# Install dependencies
npm install

# Set your token
export CATALOG_TOKEN="your_token_here"

# Run the server
node bin/server.js

Project Structure

├── bin/
│   └── server.js          # Entry point
├── src/
│   ├── mcp-server.js      # Main MCP server
│   ├── api-client.js      # Sales Layer API client
│   ├── tools/             # MCP tools
│   │   ├── catalog-tools.js
│   │   └── product-tools.js
│   └── utils/
│       └── logger.js      # Logging utility
├── examples/
│   └── claude-config.json # Example configuration
└── setup-windows.ps1     # Windows setup script

📞 Support

• Sales Layer Support: support.saleslayer.com
• API Documentation: Sales Layer API Docs

Made with ❤️ by Sales Layer

Transform your product catalog management with AI-powered assistance.