mcp-worldpay — Claude Code MCP server: Worldpay payments
An MCP server over Access Worldpay: authorize, capture, refund, tokenize cards and handle disputes from inside an AI agent.
claude mcp add --env WORLDPAY_USERNAME=<WORLDPAY_USERNAME> --env WORLDPAY_PASSWORD=<WORLDPAY_PASSWORD> --env WORLDPAY_ENTITY=<WORLDPAY_ENTITY> --env WORLDPAY_ENV=<WORLDPAY_ENV> --env WORLDPAY_API_VERSION=<WORLDPAY_API_VERSION> --transport stdio worldpay -- npx -y @codespar/mcp-worldpayWhat mcp-worldpay does
The server exposes 22 Access Worldpay tools to the agent. Card lifecycle calls sit next to create_token, get_token and update_token, the three 3DS2 steps, and dispute handling through get_dispute, defend_dispute and submit_dispute_evidence. fraud_screen runs a FraudSight check on a payment method without any authorization, while verify_account does AVS/CVC validation before a charge.
Authentication is HTTP Basic with the username and password Worldpay issued you, plus a merchant entity id. Leave WORLDPAY_USERNAME, WORLDPAY_PASSWORD or WORLDPAY_ENTITY unset and the server has nothing to connect with. WORLDPAY_ENV picks sandbox or production and starts on sandbox. The Payments API version comes from WORLDPAY_API_VERSION, v7 unless you change it.
Access Worldpay is HATEOAS-driven, so an authorization response carries action links such as payments:settle or payments:refund. Pull the trailing linkData segment out of the href and hand it to capture_payment, refund_payment or the other lifecycle calls. Omit it and the server falls back to the bare resource path, which only works on onboardings that settle by transactionReference. The package ships as 0.1.0-alpha.1, and endpoint paths can still move.
What it helps with
- validate a card with AVS/CVC before charging it
- authorize a payment, then capture or void it
- refund a payment that has already settled
- store a card as a token for repeat purchases
- answer a chargeback by accepting it or filing evidence
Example prompts for the agent
- Run an AVS/CVC check on this card without charging it
- Authorize a payment for 49.90 and capture it using its
linkData - Refund the captured payment and include the reason
How to install mcp-worldpay
Platform CLI
claude mcp add --env WORLDPAY_USERNAME=<WORLDPAY_USERNAME> --env WORLDPAY_PASSWORD=<WORLDPAY_PASSWORD> --env WORLDPAY_ENTITY=<WORLDPAY_ENTITY> --env WORLDPAY_ENV=<WORLDPAY_ENV> --env WORLDPAY_API_VERSION=<WORLDPAY_API_VERSION> --transport stdio worldpay -- npx -y @codespar/mcp-worldpayReplace <…> with your own values
Platform CLI
codex mcp add worldpay --env WORLDPAY_USERNAME=<WORLDPAY_USERNAME> --env WORLDPAY_PASSWORD=<WORLDPAY_PASSWORD> --env WORLDPAY_ENTITY=<WORLDPAY_ENTITY> --env WORLDPAY_ENV=<WORLDPAY_ENV> --env WORLDPAY_API_VERSION=<WORLDPAY_API_VERSION> -- npx -y @codespar/mcp-worldpayReplace <…> with your own values
Config file
{
"mcpServers": {
"worldpay": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-worldpay"
],
"env": {
"WORLDPAY_USERNAME": "<WORLDPAY_USERNAME>",
"WORLDPAY_PASSWORD": "<WORLDPAY_PASSWORD>",
"WORLDPAY_ENTITY": "<WORLDPAY_ENTITY>",
"WORLDPAY_ENV": "<WORLDPAY_ENV>",
"WORLDPAY_API_VERSION": "<WORLDPAY_API_VERSION>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"worldpay": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-worldpay"
],
"env": {
"WORLDPAY_USERNAME": "<WORLDPAY_USERNAME>",
"WORLDPAY_PASSWORD": "<WORLDPAY_PASSWORD>",
"WORLDPAY_ENTITY": "<WORLDPAY_ENTITY>",
"WORLDPAY_ENV": "<WORLDPAY_ENV>",
"WORLDPAY_API_VERSION": "<WORLDPAY_API_VERSION>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e WORLDPAY_USERNAME=<WORLDPAY_USERNAME> -e WORLDPAY_PASSWORD=<WORLDPAY_PASSWORD> -e WORLDPAY_ENTITY=<WORLDPAY_ENTITY> -e WORLDPAY_ENV=<WORLDPAY_ENV> -e WORLDPAY_API_VERSION=<WORLDPAY_API_VERSION> worldpay npx -y @codespar/mcp-worldpayReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-worldpay
How do I install mcp-worldpay in Claude Code?
Run `claude mcp add mcp-worldpay -e WORLDPAY_USERNAME=<WORLDPAY_USERNAME> -e WORLDPAY_PASSWORD=<WORLDPAY_PASSWORD> -e WORLDPAY_ENTITY=<WORLDPAY_ENTITY> -- npx -y @codespar/mcp-worldpay`, replacing the placeholders with your own credentials.
What does mcp-worldpay do?
It gives the agent Worldpay payment tools: authorization, capture, cancel, refund and reverse, card tokenization, 3DS2 steps, fraud screening and dispute actions.
Why does linkData matter?
Worldpay returns action links after authorization, and the trailing segment of each href addresses the operation. Without it the server targets the bare resource path, which only fits settle-by-transactionReference onboardings.
