Build Your Store (BYS) MCP Server

A Model Context Protocol (MCP) server for Build Your Store (BYS) e-commerce platform with 63 Storefront API tools for customer-facing operations.

What's New in v2.0.2

• 63 Storefront API Tools: Complete customer-facing e-commerce operations
• Admin API Removed: Streamlined for sales and customer service workflows (prevents MCP buffer overflow)
• Basic Auth Support: Added Secret API Key support for BYS instances requiring Basic Authentication
• Auto-generated Tools: Tools generated from official BYS Postman collections
• Dynamic Tool Loading: Tools loaded from JSON files for easy updates

Features

Storefront API (63 tools)

• Customer Authentication: Login, registration, password reset
• Product Discovery: Browse, search, filter products with variants and pricing
• Shopping Cart: Create, update, manage cart items
• Checkout: Complete orders, manage shipping/billing addresses
• Order Management: Track orders, view order history
• Customer Profile: Manage customer information
• Gift Cards: Support for gift card purchases and redemption
• Product Collections: Browse categorized products
• Region Support: Multi-region pricing and currency support

Note: Admin API (348 tools) has been removed to prevent MCP transport buffer overflow. For administrative operations (inventory management, order fulfillment, promotions), use the BYS Admin Dashboard or consider creating a separate Admin-focused MCP server.

Product Pricing Information

All product tools return comprehensive pricing information to enable value-emphasized sales conversations:

Price Structure

{
  "price": {
    "current": 789,           // Current price (after discount if applicable)
    "original": 6999,         // Original price (before discount)
    "currency": "INR",        // Currency code
    "has_discount": true,     // Boolean indicating active discount
    "discount_amount": 6210,  // Absolute savings (original - current)
    "discount_percentage": 88.7  // Percentage discount
  }
}

Usage in Agent Conversations

Agents should present prices in this psychologically effective sequence:

1. Original price (anchor high)
2. Discount (highlight value)
3. Current price (final attractive price)

Example:

"This product was originally priced at ₹6,999. You get an amazing 88% discount - save ₹6,210! Your special price is just ₹789."

This approach:

• Creates psychological anchoring
• Emphasizes customer value
• Increases conversion rates
• Reduces price objections

See Sales Agent Template for detailed pricing presentation guidelines.

Pricing Behavior and Region Discovery

The MCP server automatically handles regional pricing context to ensure accurate price calculations:

How it works:

1. Environment Variable Check: First checks for BYS_DEFAULT_REGION_ID environment variable
2. Auto-Discovery: If not set, automatically discovers the first available region from your store's API
3. Caching: Region is cached to avoid repeated API calls
4. Multi-Level Fallback: If region discovery fails, falls back to alternative price fields

Price Data Priority:

1. calculated_price (requires region context - most accurate, includes taxes)
2. prices array (fallback if no region)
3. Direct price fields on variant (last resort)
4. Returns null if no price data available

Configuration Example:

# Optional: Specify a default region for better performance
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."

# Without this variable, the system auto-discovers region on first request

Benefits:

• ✅ Accurate regional pricing with taxes
• ✅ Zero configuration required (auto-discovery)
• ✅ Manual override available for multi-region stores
• ✅ Graceful fallbacks ensure pricing always available when possible

Installation

1. Install via npx (recommended):

npx @olbrain/bys-mcp@latest

2. Or clone and install locally:

git clone https://github.com/olbrain-ai/olbrain-public-tools.git
cd olbrain-public-tools/mcp_servers/bys-mcp
npm install

Configuration

Environment Variables

Set these environment variables based on which APIs you need:

Required:

• BYS_STORE_URL: Your BYS store URL (e.g., https://mystore.com)

Recommended:

• BYS_STORE_ID: Your Store ID for x-store-id header (required by some BYS instances)

Optional (at least one recommended):

• BYS_PUBLISHABLE_API_KEY: Publishable API Key for Storefront API operations
• BYS_ADMIN_API_TOKEN: JWT Bearer token for Admin API operations

Optional (Pricing Optimization):

• BYS_DEFAULT_REGION_ID: Default region ID for price calculations (e.g., reg_01ABCDEF...)
  • If not set, the first available region is auto-discovered from the API
  • Improves price accuracy by providing regional context (taxes, currency)
  • Improves performance by skipping region discovery on each request
  • Format: Region ID from your store (usually starts with reg_)

Getting Credentials

Storefront API (Publishable API Key)

1. Log in to your BYS Admin panel
2. Navigate to Settings → Publishable API Keys
3. Create a new API key
4. Copy the key (starts with pk_)

Admin API (JWT Token)

1. Authenticate via /admin/auth/user/{provider} endpoint
2. Use the returned JWT token
3. Token format: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Store ID (x-store-id header)

Some BYS instances require a Store ID in the x-store-id header for all API requests.

To find your Store ID:

1. Open your BYS storefront in a browser (e.g., Chrome, Firefox)
2. Open Developer Tools (press F12 or Cmd+Option+I on Mac)
3. Go to the Network tab
4. Browse products or perform any action on your storefront
5. Look for API requests to /store/products or similar endpoints
6. Click on any request and view the Headers tab
7. Find the x-store-id header value
8. Copy this value (usually starts with store_ followed by alphanumeric characters)

Example:

x-store-id: store_01234567890abcdef

If your API returns errors like "x-store-id header is required", you must configure this value.

Example Configuration

# Storefront API only
export BYS_STORE_URL="https://mystore.com"
export BYS_STORE_ID="store_01234567890abcdef"  # Optional but recommended
export BYS_PUBLISHABLE_API_KEY="pk_01234567890abcdef"
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."  # Optional - improves pricing accuracy

# Admin API only
export BYS_STORE_URL="https://mystore.com"
export BYS_STORE_ID="store_01234567890abcdef"  # Optional but recommended
export BYS_ADMIN_API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."  # Optional - improves pricing accuracy

# Both APIs (recommended for full functionality)
export BYS_STORE_URL="https://mystore.com"
export BYS_STORE_ID="store_01234567890abcdef"  # Optional but recommended
export BYS_PUBLISHABLE_API_KEY="pk_01234567890abcdef"
export BYS_ADMIN_API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
export BYS_DEFAULT_REGION_ID="reg_01ABCDEF..."  # Optional - improves pricing accuracy

Usage

Running the Server

# Via npx
npx @olbrain/bys-mcp@latest

# Or via node
node index.js

# Or via npm
npm start

Using with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "build-your-store": {
      "command": "npx",
      "args": ["-y", "@olbrain/bys-mcp@latest"],
      "env": {
        "BYS_STORE_URL": "https://mystore.com",
        "BYS_PUBLISHABLE_API_KEY": "pk_your_key_here",
        "BYS_ADMIN_API_TOKEN": "your_jwt_token_here",
        "BYS_DEFAULT_REGION_ID": "reg_01ABCDEF..."
      }
    }
  }
}

Available Tools

Storefront API Tools (63)

Authentication & Customer

• callback_validate_authentication_callback
• register_retrieve_registration_jwt_token
• reset_password_generate_reset_password_token
• update_reset_a_customers_password
• And more...

Products

• products_list_products
• product_get_a_product
• products_list_a_product_s_variants
• And more...

Cart & Checkout

• carts_create_cart
• cart_get_a_cart
• line_items_add_line_item_to_cart
• complete_complete_a_cart
• And more...

Orders

• order_retrieve_an_order
• orders_list_orders
• And more...

Admin API Tools (348)

Products & Inventory

• products_list_products (admin version)
• products_create_product
• products_update_a_product
• products_delete_a_product
• inventory_items_list_inventory_items
• And 100+ more...

Orders & Fulfillment

• orders_list_orders (admin version)
• orders_get_an_order
• orders_update_an_order
• fulfillments_create_fulfillment
• And 50+ more...

Customers

• customers_list_customers
• customers_create_customer
• customers_update_a_customer
• And 20+ more...

Store Configuration

• promotions_list_promotions
• regions_list_regions
• tax_rates_list_tax_rates
• payment_providers_list_payment_providers
• And 100+ more...

For a complete list of all 411 tools, see tools/medusa_storefront_tools.json and tools/medusa_admin_tools.json

Architecture

Components

bys-mcp/
├── index.js                     # Node.js entry point
├── src/
│   ├── server.py               # MCP server implementation
│   ├── medusa_client.py        # HTTP client for BYS APIs
│   └── tools/
│       └── tool_loader.py      # Dynamic tool loader
├── tools/
│   ├── medusa_storefront_tools.json   # 63 Storefront tools
│   └── medusa_admin_tools.json        # 348 Admin tools
└── README.md

How It Works

1. Tool Loading: On startup, the server loads tool definitions from JSON files
2. Authentication Detection: Based on the endpoint, the client automatically uses the correct authentication method
3. Dynamic Execution: Tools are executed dynamically based on their metadata (HTTP method, endpoint, parameters)
4. MCP Protocol: Communicates with clients using the Model Context Protocol over stdio

Authentication Flow

# Storefront API
GET /store/products
Headers: { "x-publishable-api-key": "pk_..." }

# Admin API
GET /admin/products
Headers: { "Authorization": "Bearer eyJ..." }

The client automatically detects the API type from the endpoint and applies the correct authentication.

Development

Testing Locally

# Install dependencies
npm install

# Set environment variables
export BYS_STORE_URL="https://your-store.com"
export BYS_PUBLISHABLE_API_KEY="pk_..."
export BYS_ADMIN_API_TOKEN="eyJ..."

# Run the server
npm start

Adding Custom Tools

To add custom tools, edit the JSON files in tools/:

{
  "name": "custom_tool_name",
  "description": "Tool description",
  "input_schema": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  },
  "_metadata": {
    "method": "GET",
    "endpoint": "/store/custom-endpoint",
    "path_params": []
  }
}

Requirements

• BYS Version: 2.0+
• API Version: v2 (Storefront & Admin)
• Node.js: 14+
• Python: 3.7+
• Dependencies:
  • httpx (Python HTTP client)
  • mcp (Model Context Protocol)

Troubleshooting

Tools Not Loading

• Check that JSON files exist in tools/ directory
• Verify JSON syntax is valid
• Check server logs for loading errors

Authentication Errors

• Verify your API keys/tokens are correct
• Check that the Store URL is accessible
• Ensure API keys have the correct permissions

Tool Execution Failures

• Check that the endpoint exists in your BYS version
• Verify required parameters are provided
• Check BYS server logs for API errors

Changelog

v2.0.0 (2026-01-20)

• MAJOR: Complete rewrite to use API tool collections
• Added support for BYS Admin API (348 tools)
• Increased Storefront API coverage (from 14 to 63 tools)
• Added dual authentication support (Publishable Key + JWT)
• Implemented dynamic tool loading from JSON files
• Auto-generated tools from official Postman collections

v1.0.0 (2025-01-XX)

• Initial release with 14 hand-coded Storefront API tools

License

MIT

Support

For issues and feature requests, please visit: https://github.com/olbrain-ai/olbrain-public-tools/issues

Documentation

• BYS API Documentation
• BYS Storefront API
• BYS Admin API
• Model Context Protocol