MCP on the API Platform - Guide

The Global Payments Model Context ProtocoL (MCP) server on our REST API Platform provides AI agents within tools such as Claude, Windsurf and VS Code with a set of tools they can use to call Global Payments APIs and search our documentation directly from your chat interface.

The MCP server also allows you to extend your AI clients/agents capabilities by providing secure, controlled access to our resources.

The Global Payments MCP server is designed to speed up your integration workflow by allowing you to perform key tasks without leaving your IDE or chat interface. Here are three common ways developers use these tools.

Use case #1: Generating Payment Links for Testing

Instead of manually navigating the merchant portal or writing a temporary script to test your checkout flow, you can ask your AI agent to generate a live payment link instantly.

Example Prompt:
"Create a single-use payment link for 50.00 USD for order #12345."

What happens: The agent uses create_payment_link tool to call the API, returning a valid URL that you can immediately click to test the payment experience or send to a customer.

Use case #2: Debugging Integrations with Live Logs

When building a payment integration on a merchant site, you might encounter vague error messages or failed transactions. Instead of context-switching to the portal to find transaction details, you can ask the agent to pull the recent logs. The agent then has the exact error codes and transaction details in its context, allowing it to analyze your code and suggest a fix immediately.

Example Workflow:
Developer: "I'm getting a 400 error on my checkout page. Can you check the last 5 payment links I created to see what happened?"
Agent: Calls get_links and analyzes the response.
Agent Response: "I found the failed transaction. The status is FAILED with error code INVALID_CURRENCY. It looks like your code is sending 'US' instead of 'USD'. Here is the corrected line of code for your checkout.js file..."

Use case #3: Contextual Documentation Search

When you are writing code and need to know the specific parameters for an API endpoint, you can ask the agent to find the relevant docs without switching to a browser.

Example Prompt:
"How do I format the request for the Transaction API? Search the docs for the required fields."

What happens: The agent uses get_documentation to pull the specific integration guide or API reference into the chat context. It can then use that information to help you write or fix your code in real-time.

Before connecting your AI client, ensure you have the following installed on your machine:

• Node.js: Version 18.0 or higher.
• Git: To clone the repository.
• Global Payments Credentials: An App ID and App Secret from your developer account.

Unlike cloud-hosted tools, this version of the MCP server runs locally on your machine to ensure maximum security and control over your API credentials.

1. Clone the repository:

   git clone https://github.com/globalpayments/mcp-server.git
   cd mcp-server

2. Install dependencies and build:

   npm install
   npm run build

3. Configure Environment Variables:
   Create a .env file in the Typescript directory (the project root). Add your credentials:

   \\ Required: Your Global Payments App credentials (format: APP_ID:APP_SECRET)
   GPAPI_APP=your_app_id:your_app_secret
   
   \\ Optional: Set environment to SANDBOX or PROD (Default: SANDBOX)
   ENV=SANDBOX

Once built, you can connect your preferred AI editor or agent to the local server.

Important: In the configurations below, you must replace /absolute/path/to/ with the actual full file path where you cloned the repository.

The server exposes the following tools to your AI agent. The agent will automatically select the correct tool based on your natural language prompt (e.g., "Create a payment link for $50").

• Path Errors: If the agent cannot find the server, ensure you are using the absolute path (e.g., /Users/username/dev/... or C:\Users\username\dev...) in the cwd (Current Working Directory) configuration.
• Authentication: Ensure your .env file is located exactly in the Typescript folder and contains valid credentials in the APP_ID:APP_SECRET format.
• Build Status: If changes aren't reflecting, try running npm run build again to ensure the TypeScript source is compiled to the lib folder.