Voucherify Core MCP

​

What is Model Context Protocol (MCP)?

Model Context Protocol, or MCP, is an open standard that lets AI agents connect to and work with data from different platforms. It has two main parts:

• MCP client: The application where the AI agent runs, such as Claude Code, Cursor, Visual Studio Code, Windsurf, or others.
• MCP package: A service provided by another platform that defines which tools the AI can use and what data it can access. It is hosted locally by users.

​

About Voucherify Core MCP

After setting up the Voucherify Core MCP locally, you can connect AI tools directly to Voucherify. This way, these tools can read data regarding campaigns, promotion tiers, orders, products, vouchers, and more. The Voucherify Core MCP is great for:

• Building AI tools that need data from Voucherify.
• Your engineers to create complex scenarios and integrate with other MCP integrations.
• Technical marketers who want to use natural language commands to fetch Voucherify data from multiple sources for analytics and other purposes.

The Voucherify Core MCP uses a number of endpoints for reading data. To prevent accidental changes to your campaigns, validation rules, and other data, creating and updating data is currently not supported.

​

Setting up Voucherify Core MCP

You can install the Voucherify Core MCP in different tools. Follow the guides for the most popular tools, or refer to the documentation of other supported tools.

​

Prerequisites

To set up Voucherify Core MCP, you need:

• An MCP client (for example Cursor, Claude Desktop, Visual Studio Code)
• UV installed (remember to restart your client if you’ve installed UV for the first time)
• Recommended: Use a separate Voucherify server-side app ID and token for the MCP.

​

Set up Voucherify Core MCP

To set up Voucherify Core MCP:

1. Open your MCP client.
2. Add the following code snippet to the mcp.json file in your client. This step may vary depending on your client; refer to the specific documentation for details.
   Copy

   {
     "version": 1,
     "mcpServers": {
       "voucherify-core-mcp": {
         "command": "uvx",
         "args": ["voucherify-core-mcp", "--transport", "stdio"],
         "env": {
           "VOUCHERIFY_APP_ID": "<app id>",
           "VOUCHERIFY_APP_TOKEN": "<app token>",
           "VOUCHERIFY_API_BASE_URL": "https://<clusterId>.api.voucherify.io"
         }
       }
     }
   }
   

3. Copy your Voucherify server-side app ID and token from Project settings into the mcp.json.
4. Provide your Voucherify API base URL. For shared clusters:
   • Europe: https://api.voucherify.io
   • North America: https://us1.api.voucherify.io
   • Asia: https://as1.api.voucherify.io
5. Run the connection with the MCP server.
6. Open a new chat to start your conversation.

​

Cursor

In Cursor, go to:

1. Settings > Cursor Settings > MCP > Add new global MCP server.
2. Paste the configuration mentioned above into your Cursor ~/.cursor/mcp.json file. Alternatively, you can also install it in a specific project by creating .cursor/mcp.json in your project folder.
3. Open a new chat to start your conversation.

For more details, read Cursor MCP docs.

​

Claude Desktop

To configure the Voucherify Core MCP in Claude Desktop:

1. Paste the above-mentioned code snippet in the path depending on your operating system:
   • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Restart Claude Desktop app.
3. Open a new chat to start your conversation.

For more details, read Claude Desktop docs.

​

Visual Studio Code

To configure the Voucherify Core MCP in Visual Studio Code:

1. Open MCP User Configuration. Alternatively, create the .vscode/mcp.json file just for the workspace you’re working on.
2. Configure the mcp.json file as in Set up Voucherify Core MCP.
3. In the mcp.json file, click Run above voucherify-core-mcp.
4. In a new chat, select voucherify-core-mcp in the tool list and start your conversation.

For more details, read Visual Studio Code MCP docs.

​

Available functionalities

You can access the following endpoints with the Voucherify MCP to fetch data:

• Find_customer: Displays a customer’s current status and detailed information such as collected loyalty points, eligibility for rewards, and other profile data. You can use the customer’s email, source ID, or Voucherify ID.
• List_campaigns: Retrieves a list of campaigns to view active, scheduled, or completed campaigns.
• Get_campaign_summary: Displays a performance summary of ongoing campaigns, including comparisons with past activity (for example, previous week), to visualize trends and measure success over time.
• Get_promotion_tier: Fetches details about the configuration of a promotion tier, such as reward levels or thresholds that determine customer benefits.
• Qualifications: Checks and returns a customer’s eligibility for specific campaigns, promotions, or reward rules, ensuring only qualified users receive incentives.
• Get_best_deals: Returns information about better prices contextually by showing the top 5 best incentives.
  For the best results, set the Application rule to Partial in Voucherify dashboard, Redemptions section, Stacking rules tab. Read the Stacking rules article for more details.
• List_products: Retrieves the catalog of products, including attributes like pricing, availability, and categories.
• Get_voucher: Returns full details of a specific voucher, such as code, status, balance, and expiration date, to support redemption or troubleshooting.

​

Best practices

Follow these practices to get the best results.

​

Ask specific questions

• Use precise date ranges (for example “July 2025 redemptions”) instead of vague prompts like “recent redemptions”.
• Describe exactly what you need: specific campaign names, product categories, or data types.
• Broad requests (for example “all campaigns in the last 3 years”) usually lead to unclear results.

​

Add more context if necessary

If results look off, reframe your query or try again. If the AI loops or repeats itself, redirect with a new question or start a new chat with a more detailed prompt.

​

Ask more questions

Once you’ve got an answer you like, ask the client to:

• Suggest additional insights or next steps.
• Explain how it reached its conclusions to help refine your future prompts.

​

Change model

If you’re not satisfied with answers or the overall process, use a different AI model. Each model is trained on different data, has their own strengths, and is best suited for various tasks.

​

Prompt examples

Read the following prompt examples for inspiration on how to use Voucherify Core MCP:

• Find customer by email tom@example.com (or source_id, or customer_id). Return the ID, loyalty_balance, active_vouchers.
• Count total of customers in segment “VIP”. List their basic details: name, email address, source_id. Turn the data into a CSV-friendly format.
• List active campaigns with fields: ID, name, type, start_date, end_date.
• Get voucher by code “BK-4829” and show: status, redemption.count, redemption.limit, balance (for gift or loyalty cards).
• Get campaign “BK-Sept-20OFF” data: total budget, spent budget, redemption counts, and per-customer caps.
• Show the campaign with the most coupons generated. Return redemption data for this campaign.
• Show me the best performing campaign in terms of number of successful redemptions. Return the budget - the total discount value that was applied.
• Get redemptions aggregated by day between 2025-09-01 and 2025-09-03 (timezone Europe/Warsaw).
• Get best deals for a customer with this email address. They have these items in their cart: Voucherify T-shirt (SKU: VCH-TST-001, quantity: 1, price: 25 USD), Voucherify Mug (SKU: VCH-MUG-002, quantity: 2, price: 15 USD each). Suggest if there’s anything they can do to get even better deals.

​

Use examples

You can interact with the Voucherify MCP using natural language in your AI agents, just as you would with other AI tools.

​

Get best deals for a given customer

In this scenario, the user wants to learn what best deals a customer, Alex Doe, can get if they have a specific cart. The scenario used is get_best_deals. The Voucherify Core MCP ran 9 API calls to find out what best deals Alex Doe can get at the moment and what they’ll get if they meet specific conditions. In this case, one prompt was enough to propose best deals for Alex Doe, like:

• Adding one product to meet a bundle promotion,
• Take part in Friday happy hours promotion,
• Becoming a VIP customer,
• Using a gift card.

​

Get details about campaigns

In this scenario, the user wants to learn what Voucherify campaigns there are in the project and if they’re active, have time frames set, and similar details. . This gives a quick overview of needed info about campaigns. The Voucherify Core MCP runs 8 API calls to fetch the requested data. The MCP returned campaign details and summarized the campaigns by their type, status, and provided time frames. For example, the response shows:

• The Loyalty program campaign is still inactive as it is a draft;
• The Friday Happy Hours campaign is valid on Fridays, between 15:00 and 17:00;
• BLACKFRIDAY2025 is active, but the time frame is set to between 28 and 30 November 2025.

​

Troubleshooting and feedback

The Voucherify MCP is still under development and we’d love to have your feedback to improve it. Also, if you’ve encountered any issues, please let us know. Contact Voucherify support or your account manager.

​

Disclaimer

The Model Context Protocol (MCP) is a new open-source standard and may still have potential vulnerabilities. The Voucherify MCP server setup and instructions are provided “as is” and without warranties. Use is at your own risk. Voucherify is not liable for issues caused by incorrect setup, misuse, or security gaps related to MCP. If you have questions or need support, please reach out to our team - we’re here to help.