Spreedly
Spreedly MCP server -- interact with the Spreedly payments API through the Model Context Protocol
Ask AI about Spreedly
Powered by Claude Β· Grounded in docs
I know everything about Spreedly. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Spreedly MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with direct access to the Spreedly payments API. Enables LLMs to manage gateways, process transactions, tokenize payment methods, and more -- all through structured, validated tool calls.
Quick Start
Add this to your MCP client configuration:
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"spreedly": {
"command": "npx",
"args": ["-y", "@spreedly/spreedly-mcp@latest"],
"env": {
"SPREEDLY_ENVIRONMENT_KEY": "<your-environment-key>",
"SPREEDLY_ACCESS_SECRET": "<your-access-secret>"
}
}
}
}
Cursor
Edit .cursor/mcp.json in your project root:
{
"mcpServers": {
"spreedly": {
"command": "npx",
"args": ["-y", "@spreedly/spreedly-mcp@latest"],
"env": {
"SPREEDLY_ENVIRONMENT_KEY": "<your-environment-key>",
"SPREEDLY_ACCESS_SECRET": "<your-access-secret>"
}
}
}
}
VS Code
Edit .vscode/mcp.json:
{
"servers": {
"spreedly": {
"command": "npx",
"args": ["-y", "@spreedly/spreedly-mcp@latest"],
"env": {
"SPREEDLY_ENVIRONMENT_KEY": "<your-environment-key>",
"SPREEDLY_ACCESS_SECRET": "<your-access-secret>"
}
}
}
}
Getting Your Credentials
- Log into the Spreedly Dashboard
- Your Environment Key is shown on your environment's settings page
- Create or find an Access Secret under your environment's access secrets
For details, see Spreedly Credentials Documentation.
Tool Access Policy
The server controls which tools are available through three environment variable flags. All default to false -- only read-only tools are available out of the box. Enable the categories you need:
| Variable | Default | What it enables |
|---|---|---|
PAYMENT_METHOD_TOKENIZATION_ENABLED | false | Dedicated payment method tokenization tools that send raw PAN/CVV to Spreedly (create, recache) |
TRANSACTION_INITIATION_ENABLED | false | Authorizing, purchasing, capturing, voiding, refunding, and other third-party actions. See Cardholder Data Flow -- authorize, purchase, and confirm also accept optional pass-in PAN/CVV data. |
ADMINISTRATIVE_ENABLED | false | Creating/updating gateways, environments, certificates, merchant profiles, SCA providers, sub-merchants |
Recommended Configuration Profiles
Read-only / monitoring (default -- no flags needed):
"env": {
"SPREEDLY_ENVIRONMENT_KEY": "<your-environment-key>",
"SPREEDLY_ACCESS_SECRET": "<your-access-secret>"
}
Only list/show tools are available. Good for dashboards, reporting, and investigating transactions.
Transaction processing (recommended for AI-assisted payments):
"env": {
"SPREEDLY_ENVIRONMENT_KEY": "<your-environment-key>",
"SPREEDLY_ACCESS_SECRET": "<your-access-secret>",
"TRANSACTION_INITIATION_ENABLED": "true"
}
Enables authorizing, capturing, voiding, and refunding against existing gateways. Does not allow creating gateways or using dedicated card tokenization tools. Note: authorize, purchase, and confirm accept optional pass-in PAN/CVV data if the merchant's Spreedly environment permits it -- see Cardholder Data Flow.
Administrative setup:
"env": {
"SPREEDLY_ENVIRONMENT_KEY": "<your-environment-key>",
"SPREEDLY_ACCESS_SECRET": "<your-access-secret>",
"ADMINISTRATIVE_ENABLED": "true"
}
For initial environment setup -- creating gateways, merchant profiles, SCA providers. Disable once configuration is complete.
Full access:
"env": {
"SPREEDLY_ENVIRONMENT_KEY": "<your-environment-key>",
"SPREEDLY_ACCESS_SECRET": "<your-access-secret>",
"PAYMENT_METHOD_TOKENIZATION_ENABLED": "true",
"TRANSACTION_INITIATION_ENABLED": "true",
"ADMINISTRATIVE_ENABLED": "true"
}
All tool categories enabled. Use only in controlled environments or during initial setup.
Cardholder Data Flow
Five tools can accept raw cardholder data (PAN, CVV). They are controlled by two different flags:
| Flag | Tools | CHD Fields |
|---|---|---|
PAYMENT_METHOD_TOKENIZATION_ENABLED | spreedly_payment_method_create, spreedly_payment_method_recache | credit_card (full PAN, CVV), bank_account, apple_pay, google_pay |
TRANSACTION_INITIATION_ENABLED | spreedly_gateway_authorize, spreedly_gateway_purchase, spreedly_transaction_confirm | credit_card (optional pass-in PAN/CVV) |
The create and recache tools are dedicated tokenization tools -- their sole purpose is to vault raw card data in Spreedly. They are gated by PAYMENT_METHOD_TOKENIZATION_ENABLED.
The authorize, purchase, and confirm tools primarily operate on existing payment_method_token references. They also accept an optional credit_card field for pass-in payment method tokenization, which tokenizes a new card inline as part of the transaction. Whether pass-in succeeds depends on the merchant's Spreedly environment settings, not the MCP server flag. These tools are gated by TRANSACTION_INITIATION_ENABLED.
PCI scoping note: Disabling only PAYMENT_METHOD_TOKENIZATION_ENABLED still allows pass-in PAN/CVV data through transaction tools when TRANSACTION_INITIATION_ENABLED is true. To exclude all raw cardholder data flows, either disable both flags, or enable the "iFrame or Spreedly Express only" setting in your Spreedly environment -- this prevents direct API submission of payment methods, blocking pass-in tokenization on transaction endpoints regardless of MCP flag configuration.
Available Tools
Gateways (12 tools)
| Tool | Description |
|---|---|
spreedly_gateway_create | Create a new gateway connection |
spreedly_gateway_list | List all gateways |
spreedly_gateway_show | Get gateway details |
spreedly_gateway_update | Update gateway configuration |
spreedly_gateway_retain | Mark gateway for retention |
spreedly_gateway_list_supported | List all supported gateway types |
spreedly_gateway_list_transactions | List transactions for a gateway |
spreedly_gateway_authorize | Authorize a payment (hold funds) |
spreedly_gateway_purchase | Authorize and capture in one step |
spreedly_gateway_verify | Verify a payment method |
spreedly_gateway_store | Store a payment method at a gateway |
spreedly_gateway_general_credit | Issue a non-referenced credit |
Transactions (9 tools)
| Tool | Description |
|---|---|
spreedly_transaction_list | List transactions |
spreedly_transaction_show | Get transaction details |
spreedly_transaction_update | Update transaction metadata |
spreedly_transaction_capture | Capture an authorized transaction |
spreedly_transaction_void | Void a transaction |
spreedly_transaction_credit | Refund a transaction |
spreedly_transaction_complete | Complete a pending transaction |
spreedly_transaction_confirm | Confirm a pending transaction |
spreedly_transaction_transcript | Get raw gateway transcript |
Payment Methods (12 tools)
| Tool | Description |
|---|---|
spreedly_payment_method_create | Tokenize a new payment method |
spreedly_payment_method_list | List payment methods |
spreedly_payment_method_show | Get payment method details |
spreedly_payment_method_update | Update payment method metadata |
spreedly_payment_method_retain | Retain a payment method |
spreedly_payment_method_recache | Recache CVV |
spreedly_payment_method_list_transactions | List transactions for a payment method |
spreedly_payment_method_list_events | List events for a payment method |
spreedly_payment_method_delete_metadata | Delete payment method metadata |
spreedly_payment_method_update_gratis | Update without gateway interaction |
spreedly_payment_method_show_event | Show a payment method event |
spreedly_payment_method_list_all_events | List all payment method events |
Certificates (4 tools)
spreedly_certificate_create, spreedly_certificate_generate, spreedly_certificate_list, spreedly_certificate_update
Environments (4 tools)
spreedly_environment_create, spreedly_environment_list, spreedly_environment_show, spreedly_environment_update
Merchant Profiles (4 tools)
spreedly_merchant_profile_create, spreedly_merchant_profile_list, spreedly_merchant_profile_show, spreedly_merchant_profile_update
Sub-Merchants (4 tools)
spreedly_sub_merchant_create, spreedly_sub_merchant_list, spreedly_sub_merchant_show, spreedly_sub_merchant_update
Events (2 tools)
spreedly_event_list, spreedly_event_show
Protection (5 tools)
spreedly_protection_forward_claim, spreedly_protection_list_events, spreedly_protection_show_event, spreedly_protection_create_provider, spreedly_protection_show_provider
SCA (3 tools)
spreedly_sca_authenticate, spreedly_sca_create_provider, spreedly_sca_show_provider
Card Refresher (3 tools)
spreedly_card_refresher_inquiry, spreedly_card_refresher_show_inquiry, spreedly_card_refresher_list_inquiries
Network Tokenization (2 tools)
spreedly_network_tokenization_card_metadata, spreedly_network_tokenization_token_status
Common Workflows
Tokenize and Charge a Card
- Create a payment method:
spreedly_payment_method_create - Authorize against a gateway:
spreedly_gateway_authorize - Capture the authorization:
spreedly_transaction_capture
Authorize Then Capture (Two-Step)
- Authorize:
spreedly_gateway_authorize(holds funds) - Capture later:
spreedly_transaction_capture(collects funds)
Refund a Transaction
- Find the transaction:
spreedly_transaction_show - Issue a refund:
spreedly_transaction_credit
Audit Logging
When audit logging is enabled (the default), the MCP server emits structured audit log entries to stderr for every tool invocation. Logs use one-line JSON format for easy SIEM ingestion and comply with PCI DSS v4.0.1 Requirement 10.2.2. stderr is the MCP-specified channel for logging β stdout is reserved for protocol traffic and must not contain non-MCP messages.
Example Output
{"timestamp":"2026-03-05T18:30:00.000Z","eventId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","component":"spreedly-mcp","tool":"spreedly_gateway_list","environmentKey":"EXAMPLE_ENVIRONMENT_KEY","status":"success","durationMs":142,"requestId":"a1b2c3d4e5","httpStatusCode":200}
{"timestamp":"2026-03-05T18:30:01.000Z","eventId":"7c9e6679-7425-40de-944b-e07fc1f90ae7","component":"spreedly-mcp","tool":"spreedly_payment_method_create","environmentKey":"EXAMPLE_ENVIRONMENT_KEY","status":"error","durationMs":89,"requestId":"f6g7h8i9j0","httpStatusCode":422}
Each entry includes: timestamp, event ID, component identifier, tool name, environment key, success/failure status, duration, and HTTP metadata. The environmentKey is the full SPREEDLY_ENVIRONMENT_KEY (safe to log β it is not a secret). The requestId and httpStatusCode fields reflect the Spreedly API response (x-request-id header and HTTP status), enabling correlation with Spreedly's server-side logs. Both are present whenever a Spreedly API call was made. On error, httpStatusCode is null when the failure occurred before any HTTP request (e.g. input validation). On success without an API call, httpStatusCode is absent. Request and response bodies are never logged.
De-duplicating Logs
The server emits exactly one audit entry per tool invocation. However, MCP hosts (Claude Desktop, Cursor, VS Code, etc.) capture and display stderr independently from one another, and some hosts may render the same stderr line more than once in their log UI. Each entry includes a unique eventId (UUIDv4) so that downstream log pipelines can safely de-duplicate: discard any entry whose eventId you have already seen.
Configuration
| Environment Variable | Values | Default | Description |
|---|---|---|---|
SPREEDLY_MCP_LOG_LEVEL | info, silent | info | Set to silent to disable audit logging. Note: Disabling audit logs means this component will not satisfy PCI DSS Requirement 10.2.1 (audit logs enabled for all system components). Use silent only in development or non-PCI environments. |
Shared Responsibility
| Responsibility | Owner |
|---|---|
| Emit structured audit events to stderr | Spreedly MCP server |
| Capture stderr and route to SIEM/log aggregator | Customer infrastructure |
| Retain logs for 12+ months (3 months immediately available) | Customer infrastructure |
| Monitor and alert on suspicious audit events | Customer infrastructure |
Security
- Credentials are isolated in a closure -- never stored as object properties, never serializable
- All inputs are sanitized for invisible Unicode characters and injection attempts
- Error messages are redacted to prevent credential leakage
- Tool descriptions are static constants hardened against prompt injection
- Audit logs never contain request/response bodies, full keys, or secrets
- See SECURITY.md for vulnerability reporting
- See Security Guide for architecture details, credential management, and deployment recommendations
Shared Responsibility
The MCP server runs in your infrastructure. Security is shared between the server and your organization:
| Category | Spreedly MCP Server | Customer |
|---|---|---|
| Credential security | Isolates in closure; never serializable or logged | Provisions, rotates, secures storage |
| Transport security | Enforces HTTPS; redacts credentials from errors | Network segmentation, access controls |
| Input validation | Validates and sanitizes tool inputs | Configures Tool Access Policy |
| Audit logging | Emits structured JSON to stderr | Routes to SIEM; retention, monitoring |
| AI provider | Hardens tool descriptions against prompt injection | Selects provider, evaluates data privacy |
| Deployment | Minimal dependencies; npm provenance attestation | Isolates server process, keeps updated |
| PCI compliance | No cardholder data stored outside API calls | Maintains own PCI posture |
For credential rotation procedures, deployment hardening, and the full model, see the Security Guide.
Development
git clone https://github.com/spreedly/spreedly-mcp.git
cd spreedly-mcp
npm install
npm test # Run all tests
npm run typecheck # Type-check
npm run build # Build for distribution
To run the MCP server locally against a real Spreedly test environment (e.g. during development before the package is published), see CONTRIBUTING.md for setup instructions and security guidelines.
Contributing
See CONTRIBUTING.md for the full guide, including local MCP client configuration and credential handling.
- Fork the repository
- Create a feature branch
- Write tests for your changes
- Ensure all checks pass:
npm test && npm run typecheck && npm run lint - Submit a pull request
Disclaimer
See DISCLAIMER.md for information on third-party AI integration, shared responsibility, and operational risk.
License
Apache License 2.0 -- see LICENSE
