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

# Model Context Protocol (MCP) server

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

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
* 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 - payment query using transaction reference
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](/products/payments/) | Take a guest card payment. (Worldpay token and Checkout session only) |
| `create_worldpay_token` | [Payments API](/products/payments/) | Create a Worldpay token for future Customer Initiated Transactions (Checkout session only) |
| `create_hosted_payment` | [Hosted Payment Pages](/products/hosted-payment-pages/) | Create a hosted payment page link to send to your customers |
| `manage_payment` | [Payments API](/products/payments/) | Perform actions on a payment after authorization such as refund, cancel and settle |
| Payment queries  | `query_payments_by_date` | [Payment Queries API](/products/payment-queries/) | Query a payment based on the date |
| `query_payments_by_transaction_reference` | [Payment Queries API](/products/payment-queries/) | Query a payment based on the `transactionReference` |
| `query_payment_by_id` | [Payment Queries API](/products/payment-queries/) | Query a payment based on the `paymentId` |