# Mastercard Gateway MCP Server
source: https://developer.mastercard.com/mastercard-gateway/documentation/ai-integration/mc-gw-mcp-server/index.md

The Mastercard Gateway MCP Server allows AI agents to securely interact with Gateway APIs. It supports payment operations such as creating payment links, retrieving orders, and issuing refunds.

The MCP Server runs within the merchant or partner environment. It connects AI tools to Gateway APIs through the Model Context Protocol (MCP).

### Who is the Gateway MCP Server for? {#who-is-the-gateway-mcp-server-for}

The MCP Server is designed for organizations that perform payment operations using Mastercard Gateway API credentials.

**Primary users** include Enterprise merchants who use their own credentials to power internal or customer-facing AI assistants.

**Secondary users** include Payment service providers (PSPs), independent software vendors (ISVs), and marketplaces that act on behalf of merchants, have authorized access to merchant credentials, such as API keys or certificates, and already participate in payment operations, such as refunds or transaction management.

**Tertiary users** include Acquirers that provide merchant-facing operational tools.

In all cases, the MCP Server executes actions using merchant credentials. Usage must align with how those credentials are managed and authorized.

## Use cases {#use-cases}

Post-purchase customer support is a common MCP Server use case. For example, an AI assistant can retrieve orders, create payment links, or issue refunds directly within a conversation.

Typical use cases include:

1. **AI-assisted customer support**   

   Customer support assistants can retrieve orders, create payment links, and issue refunds without requiring agents to navigate merchant systems manually.

2. **AI-assisted merchant operations**   

   Internal teams can create payment links, retrieve orders, and issue refunds using natural-language requests.

3. **Conversational merchant support tools**   

   ISVs and PSPs can embed AI assistants into their platforms to perform Gateway tasks during merchant support interactions.

4. **Sales and payment collection workflows**   

   Teams can create payment links during customer conversations to help collect payments or complete purchases without switching systems.

If your use case focuses on giving AI agents access to developer documentation or enabling them to generate code snippets from that documentation, see [Model Context Protocol](https://developer.mastercard.com/platform/documentation/agent-toolkit/mcp-overview/).

## What it does {#what-it-does}

The MCP Server exposes Mastercard Gateway API operations as tools that AI assistants can use.

When a user requests a payment task, the AI assistant selects the appropriate tool, and the MCP Server executes the corresponding Gateway API request.

With the MCP Server, your AI agent can:

* Create payment links
* Retrieve orders and transactions
* Issue refunds

### Key benefits {#key-benefits}

* Users can complete common payment tasks directly from a chat interface.
* The MCP Server uses standard Gateway authentication and APIs.

## How it works {#how-it-works}

The MCP Server runs as a local MCP server that acts as a bridge between your AI assistant and Mastercard Gateway APIs.

The MCP Server receives requests from AI assistants and sends the corresponding Gateway API requests.

### Sequence diagram {#sequence-diagram}

Diagram mcp-server

### Workflow {#workflow}

1. You or your customers ask an AI assistant to complete a payment task.
2. The AI assistant identifies the appropriate MCP Server tool.
3. The MCP Server sends the corresponding Gateway API request and returns the result to the AI assistant.

To Mastercard Gateway, each request looks like a standard API call.

### Available tools {#available-tools}

The MCP Server shares these MCP tools with AI agents.

|      Tool name      |                         Description                         |
|---------------------|-------------------------------------------------------------|
| create-payment-link | Creates a payment link for a specified amount and currency. |
| get-order           | Retrieves order details and transaction history.            |
| issue-refund        | Issues a full or partial refund, based on Gateway rules.    |

### Example prompts {#example-prompts}

After setup, you can ask prompts such as:

* "Create a payment link for $100."
* "Retrieve order 123456."
* "Issue a refund for order 123456."

Note: By default, the underlying API requests for payment link creation and refund issuance use the MCP_ prefix. This prefix helps you and Mastercard Gateway identify requests initiated through the MCP Server.

### Amount handling {#amount-handling}

You can specify amounts using natural language, such as "$100." The MCP Server converts amounts into the format required by Mastercard Gateway APIs, such as minor units, before making the API call.

## Using the server {#using-the-server}

This section explains how to use the MCP Server with supported AI clients.

### Prerequisites {#prerequisites}

Before you use the MCP Server, make sure that you have:

* Node.js 18 or later
* A Mastercard Gateway merchant account
* Gateway API details
  * Merchant ID
  * API key
  * API base URL

Note: The MCP Server executes all actions using your merchant credentials. Ensure that your AI assistant is trusted and securely deployed.

### Integration with MCP clients {#integration-with-mcp-clients}

Model Context Protocol clients can connect to local tools. Supported MCP clients include VS Code, Cursor, and custom applications.

You list MCP servers in a local configuration file.

In this setup:

1. The MCP client starts the server process.
2. The client identifies the available tools.
3. The client calls tools when you ask for a task.
4. The MCP Server validates the inputs.
5. The MCP Server calls the appropriate Mastercard Gateway API.
6. The MCP Server returns results to the client.   

Install the MCP Server on the same device as your MCP client. Set the required environment variables before you start using the server.

### Configuration parameters {#configuration-parameters}

You configure the MCP Server using environment variables.

Tip: Set DEFAULT_CURRENCY and MAX_REFUND_BY_CURRENCY for agent workflows. This helps agents use consistent refund values and reduces the risk of exceeding refund limits.

<br />

|              Variable              | Required | Default Description |
|------------------------------------|----------|---------------------|
| MERCHANT_ID                        | Yes      | -                   |
| API_KEY                            | Yes      | -                   |
| API_BASE_URL                       | Yes      | -                   |
| MERCHANT_NAME                      | Yes      | -                   |
| MERCHANT_URL                       | Yes      | -                   |
| RETURN_URL                         | Yes      | -                   |
| DEFAULT_CURRENCY                   | Yes      | -                   |
| MAX_REFUND_BY_CURRENCY             | No       | Not enforced        |
| NUMBER_OF_ALLOWED_PAYMENT_ATTEMPTS | No       | 25                  |

If you do not provide the required values, the MCP Server does not start.

### Refund safety limits {#refund-safety-limits}

You can use MAX_REFUND_BY_CURRENCY to set a maximum refund amount for each currency.

If you set this value, the server denies refund requests when:

* The refund exceeds the configured limit.
* The total refunds for the order exceed the configured limit.

##### Example format: {#example-format}

    USD=100, EUR=90, GBP=74.99

Note: MAX_REFUND_BY_CURRENCY is intended as an MCP Server safety guardrail. In rare concurrent-processing scenarios, refunds may exceed the configured limit. Merchants should use additional approval, authorization, or operational controls when strict refund limits are required.

### Identify MCP-initiated transactions {#identify-mcp-initiated-transactions}

By default, the MCP Server uses the MCP_ prefix to identify activity initiated through the MCP Server.

If merchants customize or remove this prefix, they should understand these implications:

* **Operational visibility**: MCP-initiated orders and transactions may become more difficult to distinguish from activity generated by other systems for troubleshooting, monitoring, reporting, and audit purposes.

* **Refund safety controls**: The current implementation of MAX_REFUND_BY_CURRENCY relies on identifying previous MCP-initiated refund transactions. If merchants customize or remove the prefix, the MCP Server implementation should also use the new identifier. Failure to do so may affect refund safety checks.

* **Mastercard visibility**: If merchants remove the default naming convention, MCP-initiated requests may no longer be distinguishable from other Gateway API activity.

Mastercard recommends keeping the default identifier convention unless you have a specific business or technical reason to change it.

If you customize the identifier convention, make sure that an alternative mechanism consistently identifies MCP-initiated orders and transactions.
Note: The MCP Server assumes that the MCP_ prefix identifies activity generated through the MCP Server. If existing merchant order or transaction identifiers already use the MCP_ prefix, or the same customized identifier configured for the MCP Server, the server may not reliably distinguish MCP-initiated activity from activity generated by other systems.

This may affect operational reporting, troubleshooting, auditability, and features that rely on identifying previous MCP-initiated transactions, such as refund safety checks.

### Example configuration {#example-configuration}

##### MCP configuration {#mcp-configuration}

```json
{
  "mcpServers": {
    "mastercard-gateway": {
      "command": "npx",
      "args": ["-y", "@mastercard/payment-gateway-mcp"],
      "env": {
        "MERCHANT_ID": "YOUR_MERCHANT_ID",
        "API_KEY": "YOUR_API_KEY",
        "API_BASE_URL": "https://mtf.gateway.mastercard.com",
        "MERCHANT_NAME": "Your Store Name",
        "MERCHANT_URL": "https://yourstore.com",
        "RETURN_URL": "https://yourstore.com/payment-complete",
        "DEFAULT_CURRENCY": "USD",
        "MAX_REFUND_BY_CURRENCY": "USD=100,EUR=90,GBP=74.99",
        "NUMBER_OF_ALLOWED_PAYMENT_ATTEMPTS": "25"
      }
    }
  }
}
```

### One-click installation {#one-click-installation}

The MCP Server supports one-click installation for popular AI platforms.

|     Platform     |     Click to install      |
|------------------|---------------------------|
| VS Code Stable   | {Add installation button} |
| VS Code Insiders | {Add installation button} |
| Cursor           | {Add installation button} |

##### VS Code setup steps {#vs-code-setup-steps}

1. Click *Install* in Visual Studio Code (VS Code).
2. Confirm the installation prompt.
3. In your `settings.json` file, add values for these required fields:
   * MERCHANT_ID
   * API_KEY
   * API_BASE_URL
   * MERCHANT_NAME
   * MERCHANT_URL
   * RETURN_URL
   * DEFAULT_CURRENCY
4. Optionally, add values for these fields:
   * MAX_REFUND_BY_CURRENCY
   * NUMBER_OF_ALLOWED_PAYMENT_ATTEMPTS
5. Save your settings.
6. Restart VS Code.

##### Cursor setup steps {#cursor-setup-steps}

1. Click *Install* in Cursor.
2. Confirm the installation prompt.
3. In your `.cursor/mcp.json` file, add values for these required fields:
   * MERCHANT_ID
   * API_KEY
   * API_BASE_URL
   * MERCHANT_NAME
   * MERCHANT_URL
   * RETURN_URL
   * DEFAULT_CURRENCY
4. Optionally, add values for these fields:
   * MAX_REFUND_BY_CURRENCY
   * NUMBER_OF_ALLOWED_PAYMENT_ATTEMPTS
5. Save your settings.
6. Restart Cursor.

## FAQs {#faqs}

Yes. The MCP Server uses standard Mastercard Gateway APIs and authentication mechanisms. Requests sent through the MCP Server are treated the same as equivalent API requests sent directly by your applications.

Ensure that you deploy and manage your AI assistant, MCP client, and credentials according to your organization's security requirements.
The MCP Server works with any supported Mastercard Gateway API version. Mastercard recommends that you integrate with API version 100. You can identify MCP-initiated requests through specific markers in the underlying API calls, depending on the operation.

* For payment link creation, the MCP Server generates a new order ID and prefixes it with MCP_.
* For refund operations, the MCP Server reuses the existing order ID and creates a new refund transaction ID prefixed with MCP_.
* For read operations, such as retrieving orders, the MCP Server does not create new identifiers, so it does not apply an MCP-specific prefix.   

For more information, see [Identify MCP-initiated transactions](https://developer.mastercard.com/mastercard-gateway/documentation/ai-integration/mc-gw-mcp-server/index.md#identify-mcp-initiated-transactions).
No. The MCP Server acts as an execution layer between the AI assistant and Mastercard Gateway APIs.

It processes requests and returns responses but does not require a separate Mastercard-hosted data store. Any logging, monitoring, or data retention depends on how the MCP Server is deployed and configured within your environment.