Connect Spreedly to Claude: Orchestrate Global Payments and Vaulting

If you need to connect Spreedly to Claude to automate global payment routing, card vaulting, or transaction reconciliation, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM tool calls and Spreedly's REST APIs. You can either build, host, and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Spreedly to ChatGPT or explore our broader architectural overview on connecting Spreedly to AI Agents.

Giving a Large Language Model (LLM) read and write access to a critical payments orchestration layer is an engineering challenge. You have to handle strict PCI-DSS tokenization limits, map complex nested transaction schemas to MCP tool definitions, and deal with Spreedly's highly specific error states. Every time Spreedly updates a gateway integration or changes a core API parameter, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Spreedly, connect it natively to Claude, and execute complex payment workflows using natural language.

The Engineering Reality of the Spreedly API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Spreedly's API is difficult. You are not just integrating a standard CRUD application - you are integrating an orchestrator that talks to hundreds of disparate payment gateways, each with their own quirks.

If you decide to build a custom MCP server for Spreedly, you own the entire API lifecycle. Here are the specific challenges you will face:

Tokenized Data Models and State Ambiguity Spreedly operates entirely on tokens. You do not pass raw credit card numbers; you pass payment_method_token strings. When you execute a purchase, the transaction can sometimes fall into an ambiguous pending state (for example, if the upstream gateway times out). To resolve this, you must explicitly call the inquiry endpoint. However, Spreedly enforces a strict limit: each transaction supports a maximum of 200 inquiry requests. If your AI agent gets stuck in a loop trying to verify a pending transaction, it will burn through this limit and permanently lock the transaction state.

Complex Gateway Routing Schemas Spreedly supports over 100 gateways. Each gateway requires a specific set of credentials and characteristics. If you expose raw Spreedly endpoints to Claude, the model has to correctly guess the required credential schema for a given gateway_type. A managed MCP server provides exact JSON schemas for these payloads derived from the API documentation, preventing the LLM from hallucinating invalid authentication parameters.

Rate Limits and 429 Errors Spreedly enforces strict rate limits on operational endpoints. For example, the list_all_spreedly_transactions endpoint is hard-capped at 30 requests per minute per environment. If your agent is summarizing a day of transactions, it will hit this ceiling quickly.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When an upstream API returns HTTP 429, Truto passes that error to the caller. Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec (see our documentation). The caller is responsible for retry/backoff. Do not rely on the MCP server to magically absorb rate limits; you must configure your agent framework to handle standard 429 backoff.

How to Generate a Spreedly MCP Server with Truto

Truto dynamically generates MCP tools from an integration's API documentation and endpoint definitions. It exposes Spreedly's resources over a JSON-RPC 2.0 endpoint that any MCP client can consume.

Each MCP server is scoped to a single Spreedly account connection. The server URL contains a cryptographic token that encodes the account context and active tools, meaning no additional authentication boilerplate is required on the client side.

Method 1: Via the Truto UI

For teams who prefer visual configuration, you can generate an MCP server directly from the dashboard.

1. Log into Truto and navigate to the integrated account page for your Spreedly connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can name the server (e.g., "Spreedly Production Access") and optionally filter which methods the server exposes (e.g., restricting access to only read operations).
5. Copy the generated MCP server URL.

Method 2: Via the Truto API

For platform engineers building automated provisioning flows, you can generate MCP servers programmatically.

Send a POST request to /integrated-account/:id/mcp with your desired configuration.

curl -X POST "https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spreedly Vaulting and Transactions",
    "config": {
      "methods": ["read", "write"],
      "require_api_token_auth": false
    }
  }'

The API will return a JSON object containing the secure URL:

{
  "id": "mcp_abc123",
  "name": "Spreedly Vaulting and Transactions",
  "config": { "methods": ["read", "write"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/sec_789xyz..."
}

This single URL is all your Claude instance needs to discover and interact with the Spreedly tools.

Connecting the Spreedly MCP Server to Claude

Once you have the Truto MCP URL, you must register it with your Claude client. You can do this visually via the UI or programmatically via a JSON configuration file.

Method 1: Via the Claude UI

Anthropic has made it incredibly straightforward to add external servers to their desktop and web clients.

1. Open your Claude client and navigate to Settings -> Integrations.
2. Click Add MCP Server (or "Add custom connector" depending on your tier).
3. Paste the Truto MCP URL into the connection field.
4. Click Add.

Claude will immediately execute an MCP initialize handshake, request the tools/list array, and populate the context window with the available Spreedly endpoints.

Method 2: Via Manual Configuration File

For developers orchestrating Claude Desktop configurations across multiple environments, you can define the MCP server in the claude_desktop_config.json file. Truto provides an SSE (Server-Sent Events) wrapper package specifically for this use case.

Open your config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following JSON block:

{
  "mcpServers": {
    "spreedly_production": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/sec_789xyz..."
      ]
    }
  }
}

Restart Claude Desktop. The application will use Node.js to spin up a local SSE bridge that maintains a persistent connection to the remote Truto server.

Hero Tools for Spreedly Operations

Truto automatically derives dozens of tools from the Spreedly API. By analyzing the config.resources and documentation schemas, it builds highly descriptive snake_case tool names that clearly signal intent to the LLM.

Here are the critical hero tools for global payments and vaulting orchestration.

create_a_spreedly_store

This tool creates a store transaction, vaulting a payment method onto a specific gateway. It allows you to tokenize a card once and register it across multiple backend gateways for redundancy.

Contextual usage notes: This is essential for intelligent routing. You must pass both a valid gateway_token and the initial payment_method_token.

"I have a payment method token 'pm_abc123'. I need to vault this card into our backup Stripe gateway (token: 'gt_strp456'). Please run the store transaction and confirm the state is succeeded."

create_a_spreedly_purchase

This is the core execution tool for charging a vaulted card. It triggers a purchase transaction against a specified gateway.

Contextual usage notes: The tool schema enforces strict currency codes and integer amounts (usually representing cents, depending on the currency). It requires the gateway_token and at least one payment origin (like payment_method_token or credit_card payload).

"Initiate a purchase of $150.00 USD against gateway 'gt_main123' using the payment method token 'pm_user890'. Return the resulting gateway_transaction_id."

create_a_spreedly_transaction

This tool syncs a specific Spreedly transaction with its upstream gateway by triggering a status inquiry. It is primarily used to resolve transactions stuck in an ambiguous pending state.

Contextual usage notes: As noted earlier, you cannot run this indefinitely. The API hard-caps inquiries at 200 per transaction ID. Instruct Claude to only run this tool when a transaction explicitly requires state resolution.

"Transaction 'tx_555ambig' is currently showing as pending. Execute an inquiry to sync it with the gateway and tell me the final state."

list_all_spreedly_transactions

This tool lists all transactions executed in the authenticated environment, returning ordered, paginated records.

Contextual usage notes: Truto automatically normalizes the pagination parameters into limit and next_cursor. The LLM knows to pass the next_cursor unchanged to iterate through large transaction histories. Note the rate limit of 30 requests per minute.

"Pull the most recent 50 transactions from Spreedly. Summarize any that ended in a failed state and group them by the associated gateway_token."

create_a_spreedly_payment_method_delivery

Spreedly's Payment Method Distribution (PMD) allows you to forward a tokenized payment method to a secure third-party receiver endpoint in real time without touching the raw PAN.

Contextual usage notes: This requires a predefined receiver_token. It returns a transaction object that indicates whether the downstream third party accepted the payload.

"We need to distribute payment method 'pm_goldcard1' to our external booking partner. Create a payment method delivery using receiver token 'rt_partner77' and report the callback status."

create_a_spreedly_gateway

This tool provisions a new payment gateway in the Spreedly environment by specifying the gateway type and credentials.

Contextual usage notes: Spreedly requires highly specific credentials objects depending on the gateway_type (e.g., Stripe requires an API key, Braintree requires a merchant ID, public key, and private key). Claude relies on the schema definitions provided by Truto to structure this body correctly.

"Provision a new sandbox test gateway. Set the gateway_type to 'test' and confirm the token ID generated so we can route test transactions to it."

For a complete list of all available endpoints, required parameters, and schema details, visit the Spreedly integration page.

Workflows in Action

When Claude is equipped with the Spreedly MCP server, it can orchestrate multi-step payment operations that previously required custom administrative dashboards or engineer intervention.

Scenario 1: Resolving Ambiguous Transactions & Refunding

The Problem: A customer support agent needs to know if a payment actually cleared, but the system shows the transaction as "pending" due to a timeout. If it cleared, they need to void it.

User Prompt:

"Check transaction 'tx_timeout99'. If it's pending, inquire with the gateway to finalize it. If it succeeded, issue a full void against the transaction to cancel the order."

Execution Steps:

1. Claude calls get_single_spreedly_transaction_by_id with id: "tx_timeout99".
2. Claude observes the state: "pending"Ref in the response payload.
3. Claude calls create_a_spreedly_transaction (the inquiry endpoint) passing the same ID to force a sync with the gateway.
4. The inquiry returns state: "succeeded".
5. Claude immediately calls create_a_spreedly_void using transaction_token: "tx_timeout99".
6. Claude replies to the user: "The transaction was stuck in pending. I forced a sync and confirmed it had actually succeeded. I have successfully voided the transaction. The order is canceled."

sequenceDiagram
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Spreedly as Spreedly API
  Claude->>Truto: Call get_single_spreedly_transaction_by_id
  Truto->>Spreedly: GET /v1/transactions/tx_timeout99.json
  Spreedly-->>Truto: 200 OK (state: pending)
  Truto-->>Claude: JSON response
  Claude->>Truto: Call create_a_spreedly_transaction (Inquiry)
  Truto->>Spreedly: POST /v1/transactions/tx_timeout99/inquire.json
  Spreedly-->>Truto: 200 OK (state: succeeded)
  Truto-->>Claude: JSON response
  Claude->>Truto: Call create_a_spreedly_void
  Truto->>Spreedly: POST /v1/transactions/tx_timeout99/void.json
  Spreedly-->>Truto: 200 OK (state: succeeded)
  Truto-->>Claude: JSON response

Scenario 2: Multi-Gateway Vaulting

The Problem: A DevOps engineer needs to migrate a batch of saved payment methods from a legacy gateway to a newly provisioned European gateway for geographic compliance.

User Prompt:

"Look up the last 5 successful transactions on gateway 'gt_legacyus'. Take the payment method tokens from those transactions and vault them into our new European gateway ('gt_europe55'). Verify they all stored correctly."

Execution Steps:

1. Claude calls list_all_spreedly_gateway_transactions using gateway_token: "gt_legacyus".
2. Claude extracts the payment_method.token fields from the 5 most recent records where succeeded is true.
3. Claude loops through the tokens, calling create_a_spreedly_store for each one, using gateway_token: "gt_europe55" and the extracted payment_method_token.
4. Claude monitors the responses, checking that each store operation returns succeeded: true.
5. Claude outputs a summary table confirming the original transaction IDs alongside the new store transaction tokens.

Security and Access Control

Exposing a payment orchestration API to an AI agent requires strict governance. Truto handles this at the MCP token generation layer, meaning security rules are hardcoded into the connection URL itself and cannot be bypassed by LLM prompt injection.

• Method Filtering: You can restrict a server to specific operations via the config.methods array. Passing ["read"] limits Claude to get and list operations, ensuring it can audit transactions without ever initiating a charge.
• Tag Filtering: Limit the available tools to specific resources using config.tags. This allows you to generate distinct MCP URLs for distinct agent personas (e.g., an agent that only has access to receivers).
• Expiration Constraints: You can set an expires_at ISO datetime when generating the server. Once the timestamp passes, the internal KV token is automatically purged, instantly killing the MCP connection.
• Secondary Authentication (require_api_token_auth): For critical financial infrastructure, mere possession of the URL may not be secure enough. Enabling this flag forces the MCP client to also pass a valid Truto API token in the headers, adding a crucial layer of identity verification.

By leveraging Truto's managed infrastructure, you bypass the massive boilerplate of auth rotation, schema definition, and token lifecycle management, letting your team focus entirely on building autonomous payment workflows.