CheckMCC Skill#

Look up credit card rewards eligibility for any merchant. Returns which cards earn bonus rewards at a given store based on its MCC (Merchant Category Code).

Base URL#

All API calls go to the configured baseUrl (default: https://check-mcc.com).

Commands#

1. Lookup by Domain ( check-mcc lookup)#

Look up a merchant by its website domain. Returns MCC code, category, and eligible cards.

When to use: User mentions a website or online store (e.g., "shopee.sg", "amazon.com").

text

GET {baseUrl}/api/store-by-domain?domain={domain}&region={region}

Parameters:

• domain (required) — The merchant's domain (e.g., amazon.com, shopee.sg). Protocol, www, and paths are auto-stripped.
• region (optional) — SG (Singapore) or US (United States). Defaults to SG if omitted.

Response:

json

{
  "id": "...",
  "Store": "Amazon",
  "MCC": "5912",
  "Country": "US",
  "Category": "Drug Stores and Pharmacies",
  "type": "online",
  "url": "https://amazon.com",
  "eligibleCards": [
    {
      "name": "Citi Rewards Card",
      "shortName": "CRMC",
      "eligible": true,
      "reason": "4 mpd on online spend",
      "mpd": "4",
      "spendCap": "$1,000/month"
    },
    {
      "name": "DBS Woman's World Card",
      "shortName": "WWMC",
      "eligible": false,
      "reason": "Excluded: insurance and hospitals"
    }
  ]
}

On 404: The merchant is not in the database. Suggest the user submit it via the website.

2. Search by Name ( check-mcc search)#

Search for merchants by name. Returns matching store names and their MCC codes.

When to use: User names a store but doesn't provide a domain (e.g., "Starbucks", "NTUC FairPrice").

text

GET {baseUrl}/api/merchants/search?q={query}

Parameters:

• q (required) — Search query. Case-insensitive partial match.

Response:

json

{
  "merchants": [
    { "Store": "Starbucks", "MCC": 5814 },
    { "Store": "Starbucks Coffee", "MCC": 5814 }
  ],
  "userDisabledCards": null
}

If multiple results are found, present them to the user and ask which one they mean. If a single clear match is found, proceed to look up card eligibility using the MCC code.

3. Card Eligibility by MCC ( check-mcc cards)#

Get card eligibility for a specific MCC code. Use when you already know the MCC (e.g., from a search result or the user provided it directly).

When to use: User asks about cards for a known MCC code (e.g., "what cards for MCC 5814?") or after getting MCC from a search.

text

GET {baseUrl}/api/store-by-domain?domain=_mcc_{mcc}&region={region}

Alternatively, if you have a merchant name, search first and then use the domain lookup for full card details.

4. Validate MCC Code#

Check if an MCC code is valid.

text

GET {baseUrl}/api/mcc/codes

Response:

json

{
  "codes": ["0001", "0002", ..., "9999"]
}

Use this to validate a user-provided MCC before looking up cards.

Workflow#

Follow this decision tree when a user asks about card rewards:

1. User provides a domain/URL → Use lookup directly
2. User provides a store name → Use search to find the merchant, then lookup on the matching domain for card details
3. User provides an MCC code → Validate with codes endpoint, then explain the category and card eligibility
4. Ambiguous result → Show the user the options and ask them to clarify

Presenting Results#

When showing card eligibility to the user:

1. Lead with eligible cards — These earn bonus rewards at this merchant

2. Format clearly: text

   Best cards for {Store} (MCC {code} - {Category}):
   
   ✅ Citi Rewards Card — 4 mpd on online spend (cap: $1,000/month)
   ✅ UOB PPV — 4 mpd on mobile contactless payments
   
   ❌ DBS Woman's World Card — Excluded: insurance and hospitals
   
   

3. Include the MCC code and category so the user understands why certain cards qualify

4. Note spend caps and special conditions when present in the response

Region Handling#

• The API supports region=SG (Singapore) and region=US (United States)
• Different regions return different card eligibility lists (different card portfolios)
• If the user doesn't specify a region, use the configured defaultRegion
• SG cards: DBS, UOB, OCBC, HSBC, Citi Singapore
• US cards: Chase, Amex, Citi US, Capital One, etc.

Error Handling#

• 404 on lookup: Merchant not found. Tell the user: "This merchant isn't in our database yet. You can submit it at check-mcc.com"
• 400 on lookup: Invalid domain format. Ask the user to provide a valid domain
• Empty search results: No merchants match. Suggest trying a different name or partial name
• API errors (5xx): Temporary issue. Suggest trying again later

Examples#

User: "Which card should I use at Shopee?" You: Search for "Shopee" → find shopee.sg → lookup domain → show eligible cards

User: "Best card for Amazon?" You: Lookup amazon.com → show eligible cards for the user's region

User: "What's the MCC code for restaurants?" You: Explain MCC 5812 (Eating Places) and 5814 (Fast Food), then offer to look up card eligibility

User: "check-mcc lookup godaddy.com" You: Directly call lookup with domain=godaddy.com → show results