Supported Tools

Learn what you can do with ValueMapper MCP tools.

Public Tools

These tools are available without authentication.

get_discoverable_promotions

Discover shops with active promotions. Returns shops that have active promotions available through the Reward Wallet. Each shop includes a preview of up to 3 promotions with discount details.

Results are ordered by the most recently created promotion-channel association (newest first).

Parameters:

Parameter	Type	Required	Description
limit	number	No	Maximum number of shops to return (default: 10, max: 50)
offset	number	No	Number of shops to skip before returning results for pagination (default: 0)
featured	boolean	No	Filter by featured shops. Pass true for featured only, false for non-featured only, or omit for all shops.
categories	string[]	No	Filter by brand categories. Only returns promotions from brands matching any of these categories.
countryCode	string	No	Filter by country code (ISO 3166-1 alpha-2, e.g. "US", "CA"). Only returns promotions from shops that ship to the specified country.

Example prompts:

• "Find new shops with active promotions"
• "Show me stores that have discounts available"
• "Discover promotion opportunities for my reward wallet"
• "What shops have the best deals right now?"
• "Find electronics promotions"
• "Show me fashion and clothing deals"
• "Find promotions available in Canada"
• "Show me US promotions in the fashion category"

Example response:

Found 2 shops with active promotions:

**Summer Sale**
  Discount: 20% off
  Shop: Acme Brand (acme-brand.com)
  Categories: Fashion, Clothing
  Description: Premium fashion for every occasion
  Shop Logo: https://cdn.shopify.com/acme-logo.png

**New Customer Welcome**
  Discount: $10 credit
  Shop: Acme Brand (acme-brand.com)

**Flash Sale**
  Discount: 30% off
  Shop: Best Deals Co (best-deals.myshopify.com)
  Ends: 2025-12-31

Authenticated Tools

These tools require authentication. See MCP Authentication for setup instructions.

get_account

Get the authenticated account details including connected services (Shopify, Tremendous).

Parameters: None

Example prompts:

• "Show me my account details"
• "What services are connected to my account?"
• "Get my ValueMapper account information"

Example response:

# Account: My Store

UUID: abc123-def456-ghi789
Status: Active

## Connected Services
  - **Shopify** (SHOPIFY)
    Status: Enabled
    Scope: read_products,write_discounts
    Shop: my-store.myshopify.com

  - **Tremendous** (TREMENDOUS)
    Status: Enabled
    Scope: rewards
    Campaigns: Summer Rewards, New Customer Welcome

get_promotions

Get all promotions for the authenticated account including discount details, rules, redemption channels, and connected services.

Parameters:

Parameter	Type	Required	Description
uuid	string	No	Optional promotion UUID to filter promotions.

Example prompts:

• "Show me all my promotions"
• "List my active promotions"
• "What promotions do I have set up?"
• "Get details about my discount campaigns"

Example response:

# Promotions (3 total)

Account UUID: abc123-def456-ghi789

## Summer Sale
- **UUID**: promo-123
- **Status**: Active
- **Type**: DISCOUNT
- **Subject**: ORDER
- **Discount**: 20% off
- **Brand**: My Brand
- **Connected Service**: Shopify (SHOPIFY)
- **Date Range**: 2024-06-01 - 2024-08-31
- **Rules**: 2 rule(s)
- **Redemption Channels**: ONLINE, IN_STORE

## New Customer Welcome
- **UUID**: promo-456
- **Status**: Active
- **Type**: CREDIT
- **Subject**: CUSTOMER
- **Discount**: $10 credit
- **Brand**: My Brand
- **Redemption Channels**: ONLINE

get_contacts

Get contacts for the authenticated account with optional filters by contact UUID, email, and Shopify ID.

Parameters:

Parameter	Type	Required	Description
uuid	string	No	Optional contact UUID filter.
email	string	No	Optional contact email filter.
shopifyId	string	No	Optional Shopify customer ID filter.

Example prompts:

• "List my contacts"
• "Find contact by email jane@example.com"
• "Find contact by Shopify customer ID"

get_redemption_codes

Get redemption codes for a promotion in the authenticated account, with optional filters.

By default, this tool returns only the latest redemption code. To include more, pass redemptionsCount.

Parameters:

Parameter	Type	Required	Description
promotionUuid	string	Yes	Promotion UUID to fetch redemption codes for.
redemptionsCount	number	No	Number of latest redemption codes to return (default: 1).
code	string	No	Optional redemption code value filter.
redeemed	boolean	No	Optional filter by redeemed status.
recipientEmail	string	No	Optional filter by recipient email.
recipientPhone	string	No	Optional filter by recipient phone.

Example prompts:

• "Show redemption codes for promotion <uuid>"
• "Show the latest 3 redemption codes for promotion <uuid>"
• "Find unredeemed codes for promotion <uuid>"
• "Find redemption code sent to jane@example.com"

Authentication

Authenticated tools use OAuth in MCP clients that support auth prompts.

For full setup, browser-auth troubleshooting, and manual API token fallback, see MCP Authentication.

Tool Naming Convention

All ValueMapper MCP tools follow the naming pattern get_* or create_* to clearly indicate their purpose. Tools are designed to be intuitive for AI assistants to understand and use appropriately based on user requests.

Rate Limits

ValueMapper MCP follows the same API request limits as the GraphQL API:

• General limit: 180 requests per minute
• Burst limit: Short bursts above the general limit may be allowed

What to do if you're rate-limited

If you encounter rate limiting:

1. Wait a few seconds before retrying
2. Reduce the frequency of requests
3. Use the limit parameter to request fewer results per call

Coming Soon

Additional MCP tools are planned for future releases:

• Credit management — View and manage customer credit balances
• Promotion management — Create and update promotions via AI assistants

Check the Changelog for updates on new MCP tools.