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

$3

- 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:

$3

json

{

  "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

  }

}





$3



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.



$3



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:

bash

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):

bash

npx @olbrain/bys-mcp@latest





2. Or clone and install locally:

bash

git clone https://github.com/olbrain-ai/olbrain-public-tools.git

cd olbrain-public-tools/mcp_servers/bys-mcp

npm install





Configuration



$3



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_

)



$3



#### 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.



$3

bash

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



$3

bash

Via npx

npx @olbrain/bys-mcp@latest



Or via node

node index.js



Or via npm

npm start





$3



Add to your Claude Desktop configuration (

claude_desktop_config.json

):

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



$3



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...



$3



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



$3



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





$3



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



$3

python

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



$3

bash

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





$3



To add custom tools, edit the JSON files in

tools/

json

{

  "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



$3

- Check that JSON files exist in

tools/` directory
- Verify JSON syntax is valid
- Check server logs for loading errors

$3

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

$3

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

Changelog

$3

- 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

$3

- 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

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

Features

$3

Product Pricing Information

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

$3

json

{

  "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

  }

}





$3



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.



$3



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:

bash

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):

bash

npx @olbrain/bys-mcp@latest





2. Or clone and install locally:

bash

git clone https://github.com/olbrain-ai/olbrain-public-tools.git

cd olbrain-public-tools/mcp_servers/bys-mcp

npm install





Configuration



$3



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_

)



$3



#### 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.



$3

bash

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



$3

bash

Via npx

npx @olbrain/bys-mcp@latest



Or via node

node index.js



Or via npm

npm start





$3



Add to your Claude Desktop configuration (

claude_desktop_config.json

):

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



$3



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...



$3



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



$3



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





$3



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



$3

python

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



$3

bash

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





$3



To add custom tools, edit the JSON files in

tools/

json

{

  "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



$3

- Check that JSON files exist in

tools/` directory
- Verify JSON syntax is valid
- Check server logs for loading errors

$3

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

$3

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

Changelog

$3

- 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