Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt

Use this file to discover all available pages before exploring further.

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. You host it locally.
Currently, only the local MCP package is supported.Voucherify developers are planning to work on a remote MCP server. Reach out to Voucherify support or your Technical Account Manager if you’re interested in this solution.

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

​
Voucherify Core MCP GitHub repo

To explore Voucherify Core MCP test engine, run it from source, or contribute, visit Voucherify Core MCP repo. The repo also includes Python test scenarios showing MCP capabilities.

​
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

Open your MCP client.
2

Add the configuration snippet

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

Add your credentials

Copy your Voucherify server-side app ID and token from Project settings into the mcp.json.
4

Set the API base URL

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

Run the connection with the MCP server.
6

Start a conversation

Open a new chat to start your conversation.

​
Client-specific setup

To set up Voucherify Core MCP in specific clients:
In Cursor, go to:
1

Open MCP settings

Go to Settings > Cursor Settings > MCP > Add new global MCP server.
2

Paste the configuration

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

Start a conversation

Open a new chat to start your conversation.
For more details, read Cursor MCP docs.
Starting from Cursor 1.0, click Add voucherify-core-mcp MCP server to Cursor for instant installation.

​
Available functionalities

You can access the following endpoints with the Voucherify MCP to fetch data:
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.
Retrieves a list of campaigns to view active, scheduled, or completed campaigns.
Displays a performance summary of ongoing campaigns, including comparisons with past activity (for example, previous week), to visualize trends and measure success over time.
Fetches details about the configuration of a promotion tier, such as reward levels or thresholds that determine customer benefits.
Checks and returns a customer’s eligibility for specific campaigns, promotions, or reward rules, ensuring only qualified users receive incentives.
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.
Retrieves the catalog of products, including attributes like pricing, availability, and categories.
Returns full details of a specific voucher, such as code, status, balance, and expiration date, to support redemption or troubleshooting.
Estimates the number of points a customer will receive in a given loyalty campaign for a specific order through earning rules with the order-paid type.Identify your customer through (ID, source ID, or email) and provide details regarding the order, like ordered items (name or ID and quantity). The MCP will return the estimated number of points.
This scenario returns only an estimation, not a precise point value. If a campaign includes tiers, mappings, and multiple earning rules, the calculation becomes more complex. During final calculation, a customer may change tiers and earn more or fewer points depending on other factors.

​
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.
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.
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.
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.
The number of API calls made by the Voucherify MCP depends on your question. Complex queries, like get best deals for a given customer, will need more API calls, while simple questions can be limited to just a few or even one, like get campaign summary. The MCP client will ask for confirmation to make an API call.The API calls made with the Voucherify MCP are included in your billing period.

​
Use examples

You can interact with the Voucherify MCP using natural language in your AI agents, just as you would with other AI tools.
In this scenario, you want to learn what best deals a customer, Alex Doe, can get if they have a specific cart. The scenario used is get_best_deals.
Voucherify Core MCP best deals example - prompt
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.
Voucherify Core MCP best deals example - response
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.

​
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, 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, reach out to our team - we’re here to help.
Last modified on April 20, 2026