# Model Context Protocol (MCP) server

Our MCP server makes it easy to enable payment and payout related actions in your automated operational workflows.

Preview
This feature is for preview only and is subject to change.

Local
## Local

### 1. Get the code

Github Repo
Clone the repository: github.com/Worldpay/worldpay-mcp

NPM (coming soon)

```bash
npm i @worldpay/worldpay-mcp
```

dockerhub (coming soon)

```

```

### 2. Run locally

Configure your client to use either stdio or run the HTTP server.

For tools such as `take_guest_payment` you must set the `merchant.entity` in the environment `.env` config. Multi entity support is under consideration.

Claude
Create the `/dist` folder:


```bash
npm install && npm run build
```

* Configure your client to point to `dist/server-stdio.js` and use the stdio config below:
  * Claude desktop config: `Settings > Developer > Edit Config`
  * You should see a running icon on the same config page if successful



```JSON claude_desktop_config.json
{
    "mcpServers": {
        "worldpay": {
            "name": "worldpay-server",
            "command": "node",
            "args": [
                "{PATH TO server-stdio.js e.g. /Users/bob/git/worldpay-mcp/dist/server-stdio.js}"
            ],
            "env": {
                "WORLDPAY_USERNAME": "USERNAME",
                "WORLDPAY_PASSWORD": "PASSWORD",
                "WORLDPAY_URL": "https://try.access.worldpay.com",
                "MERCHANT_ENTITY": "default"
            }
        }
    }
}
```

### 3. Usage

A couple of examples of what this looks like when integrated to Claude:

div
#### Query for a payment using transaction reference

* Text: `Query payment using transaction reference claude-123`
* Toolset/tool: Payment queries / query_payments_by_transaction_reference
* Prompt to confirm details before query


Claude - payment query using transaction reference
div
#### Create a Hosted Payment Pages (HPP) link

* Text: `Create a payment link for 10 GBP`
* Toolset/tool: Hosted payment / create_hosted_payment
* Prompt to confirm details before link creation


Claude - create a Hosted Payment Pages link
HTTP server
Create `.env` file with credentials and config. Copy from `.env.example`.


```Bash .env
WORLDPAY_USERNAME={add username}
WORLDPAY_PASSWORD={add password}
WORLDPAY_URL=https://try.access.worldpay.com
MERCHANT_ENTITY=default
```

Run the server locally:


```bash
npm install && npm run build && npm run start
```

**-- OR --**

Build and run as a container:


```bash
docker build -t worldpay/mcp .  
docker run -p 3001:3001 --env-file .env localhost/worldpay/mcp:latest
```

Hosted (coming soon)
## Tools supported

| Toolset | Tools  | API  | Description |
|  --- | --- | --- | --- |
| Payment  | `take_guest_payment` | [Payments API](/access/products/payments/) | Take a guest card payment. (Worldpay token and Checkout session only) |
| `create_worldpay_token` | [Payments API](/access/products/payments/) | Create a Worldpay token for future Customer Initiated Transactions (Checkout session only) |
| `create_hosted_payment` | [Hosted Payment Pages](/access/products/hosted-payment-pages/) | Create a hosted payment page link to send to your customers |
| `manage_payment` | [Payments API](/access/products/payments/) | Perform actions on a payment after authorization such as refund, cancel and settle |
| Payment queries  | `query_payments_by_date` | [Payment Queries API](/access/products/payment-queries/) | Query a payment based on the date |
| `query_payments_by_transaction_reference` | [Payment Queries API](/access/products/payment-queries/) | Query a payment based on the `transactionReference` |
| `query_payment_by_id` | [Payment Queries API](/access/products/payment-queries/) | Query a payment based on the `paymentId` |
| Payouts  | `query_account_payouts` | [Account Payouts API](/access/products/account-payouts) | Query for payouts |
| Agentic commerce  | `create_delegate_token` | [Sessions API](/access/products/sessions/) | Create an ACP delegate payment token. See [Agentic Commerce Protocol (ACP)](/access/products/ai/acp) for details. |