Connect Spreedly to ChatGPT: Manage Payment Gateways and Transactions

If you need to connect Spreedly to ChatGPT to automate payment gateway provisioning, audit transaction states, or manage vaulted cards, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calls and Spreedly's complex REST APIs. You can either build 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 Claude, check out our guide on connecting Spreedly to Claude or explore our broader architectural overview on connecting Spreedly to AI Agents).

Giving a Large Language Model (LLM) read and write access to a payment orchestration platform is a severe engineering challenge. You are not just dealing with simple CRUD operations. You are navigating PCI compliance, tokenized payment methods, async 3D Secure (3DS2) authentications, and strict rate limits. Every time Spreedly adds a new gateway type or updates its Strong Customer Authentication (SCA) requirements, your custom server code must be updated, re-tested, and deployed.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Spreedly, connect it natively to ChatGPT, 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 via JSON-RPC, the reality of implementing it against Spreedly's API is painful.

If you decide to build a custom MCP server for Spreedly, you own the entire API lifecycle. Here are the specific integration challenges that break standard REST assumptions when working with payment orchestration:

The Triple-Token Architecture

Spreedly operates on a strict dependency graph using tokens rather than raw IDs. To execute a single purchase, an AI agent must successfully chain together three independent entities: an Environment Key, a Gateway Token, and a Payment Method Token. If you tell ChatGPT to "charge the customer $50," the LLM must know how to list gateways to find the active processor, retrieve the vaulted payment method token, and construct a highly specific payload combining both. If your MCP server does not expose these endpoints with explicitly mapped JSON schemas, the LLM will hallucinate the identifiers and the charge will fail.

Async States and Callback Polling

Payment orchestration is rarely synchronous. Operations like create_a_spreedly_export (batch exporting payment methods) or network tokenization return an immediate pending state. The actual result is posted to an async callback URL. ChatGPT cannot passively listen for webhooks. Your system prompt and MCP server must be designed to instruct the LLM on how to verify asynchronous states - for example, utilizing the update_a_spreedly_transaction_by_id tool to force a sync inquiry with the upstream gateway to resolve ambiguous or pending transaction states.

Rate Limits and 429 Handling

Spreedly enforces strict rate limits across its environments - for example, list_all_spreedly_transactions is heavily throttled. Truto does not silently absorb rate limits, retry, or apply backoff on rate limit errors. When the upstream Spreedly API returns an HTTP 429 Too Many Requests, Truto passes that exact error directly to the caller (the LLM). Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - whether it is your custom agent framework or ChatGPT - is strictly responsible for interpreting the failure and applying exponential backoff logic before attempting to call the tool again.

Strict Schema Requirements for SCA

Strong Customer Authentication (SCA) and 3DS2 require highly nested payload structures containing browser fingerprints, device info, and merchant profiles. A standard generic proxy will fail to guide the LLM. You need an MCP layer that extracts the exact query_schema and body_schema from the API documentation and injects them as capabilities into the LLM context.

Architecting the Managed MCP Server

Instead of building a stateful JSON-RPC server from scratch, Truto dynamically generates tools based on the integration's documented resources. When you create a Spreedly MCP server in Truto, it does not cache or pre-build tools. On every tools/list request from ChatGPT, Truto reads the latest Spreedly API schemas, normalizes them into a flat input namespace (combining query and body parameters), and returns them to the model.

Because tool execution uses Truto's underlying proxy API, requests hit Spreedly directly. There is no middle-tier caching of your transaction data. (You can read more about our zero-data retention MCP architecture here). The LLM gets raw access to the API endpoints defined by the configuration you choose.

How to Create the Spreedly MCP Server

Truto scopes each MCP server to a single integrated account (a specific authenticated connection to Spreedly). You can create the server via the Truto dashboard or programmatically via the API.

Method 1: Via the Truto UI

1. Log into your Truto environment and navigate to the integrated account page for your connected Spreedly instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Define a recognizable name (e.g., "Spreedly Production Agent").
5. Select your configuration constraints. You can restrict the server to only read methods to prevent the LLM from accidentally processing charges, or apply tags to limit access to specific resources.
6. Copy the generated MCP Server URL. (This URL contains a hashed cryptographic token - do not expose it publicly).

Method 2: Via the Truto API

For platform engineers building multi-tenant AI products, you can dynamically generate MCP servers for your end-users via the Truto REST API. This generates a secure token stored in cloud infrastructure, schedules an optional expiration alarm, and returns the endpoint.

// POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp
// Headers: Authorization: Bearer {truto_api_token}
 
{
  "name": "Spreedly FinOps Automation",
  "config": {
    "methods": ["read", "write"], 
    "tags": ["transactions", "gateways"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

The API response returns the URL you will pass to your LLM client:

{
  "id": "mcp_8f7d6c5b4a",
  "name": "Spreedly FinOps Automation",
  "url": "https://api.truto.one/mcp/abc123def456...",
  "expires_at": "2026-12-31T23:59:59Z"
}

How to Connect the MCP Server to ChatGPT

Once you have your Truto MCP URL, you must register it with your LLM interface. ChatGPT uses this URL to send an initialize handshake, followed by tools/list to discover what Spreedly actions it can perform.

Method A: Via the ChatGPT UI

If you are using ChatGPT Pro, Plus, Business, Enterprise, or Education accounts, you can add the connector directly in the application:

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Toggle Developer mode to ON (MCP support requires this feature flag).
3. Under the MCP servers / Custom connectors section, click to add a new server.
4. Enter a name: Spreedly (Truto).
5. Paste the Truto MCP URL generated in the previous step.
6. Click Save. ChatGPT will immediately perform the JSON-RPC handshake, fetching the Spreedly tools.

Method B: Via Manual Config (Proxy CLI)

For developers building custom CLI tools or integrating with headless agent frameworks (like LangGraph or CrewAI) that expect standard stdio MCP servers, you can bridge the remote Truto HTTP URL using the official Server-Sent Events (SSE) proxy:

Create an mcp_config.json file:

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

Your agent framework will spawn the Node process, which will tunnel standard input/output over HTTP to Truto's edge routers, keeping the connection entirely serverless.

Security and Access Control

Exposing an enterprise payment orchestration platform to a generative AI model requires zero-trust boundaries. Truto enforces this at the configuration level:

• Method Filtering: By defining config.methods: ["read"], the MCP proxy strictly removes access to create, update, and delete tools. The LLM can audit transactions but cannot issue refunds or create gateways.
• Tag Filtering: You can restrict the toolset to specific Spreedly resources by defining config.tags: ["gateways"]. Resources without these tags are stripped from the tools/list response.
• API Token Authentication (require_api_token_auth): By default, the MCP URL acts as a bearer token. If you set require_api_token_auth: true, Truto requires the client to pass a valid Truto API token in the Authorization header. If the token is missing, the middleware immediately rejects the request.
• Automatic Expiration (expires_at): For temporary support escalations, set an ISO datetime. Truto's durable object infrastructure will automatically delete the server token and KV entry when the time expires, revoking LLM access instantly.

Spreedly Hero Tools for ChatGPT

The full integration exposes dozens of endpoints covering everything from receivers to sub-merchants. For this guide, we highlight the core tools that drive high-value automation workflows.

1. list_all_spreedly_transactions

Lists all transactions in the authenticated environment, returned in ordered, paginated form. This is the primary tool for auditing payment flow, searching for failed transactions, or calculating daily volume. Truto automatically injects limit and next_cursor logic.

"Audit the last 50 transactions and give me a summary of any that are currently stuck in a 'pending' state, grouped by currency code."

2. create_a_spreedly_transaction

Triggers a sync with the underlying gateway by initiating a status inquiry. This resolves transactions that are stuck in an ambiguous state due to network timeouts between Spreedly and the payment processor.

"Take this transaction token (TToken123) and force a sync with the gateway to resolve its state. Tell me if it moved to succeeded or failed."

3. create_a_spreedly_gateway

Provisions a new gateway connection in Spreedly by specifying the gateway type (e.g., Stripe, Adyen) and required credentials. This is useful for IT orchestration agents standing up new processing environments.

"Provision a new 'stripe' gateway in our environment. Here are the necessary gateway credentials..."

4. create_a_spreedly_purchase

Creates a purchase transaction by charging a vaulted payment method at a specified gateway. Requires precise handling of the gateway_token, amount, and the payment_method_token.

"Process a charge of 100 USD against gateway token GToken789 using the vaulted payment method token PToken456. Return the resulting gateway transaction ID."

5. create_a_spreedly_refund

Processes a refund (credit) against a previously captured transaction. This tool requires the original transaction_token and can be utilized by customer support agents resolving billing disputes.

"Issue a full refund for transaction TToken999 and confirm the state of the resulting credit transaction."

6. create_a_spreedly_sca_authentication

Creates a Spreedly SCA (3DS2) authentication for a payment method and amount. This is vital for European transactions requiring Strong Customer Authentication before a charge can be captured.

"Initiate a 3DS2 SCA authentication for payment method PToken111. Use the standard browser info payload I provide and return the authentication value."

For the complete inventory of available proxy endpoints, schemas, and resource fields, review the Spreedly integration page.

Workflows in Action

How do these tools combine to solve real operational problems? Here are two detailed persona-specific workflows demonstrating multi-step AI orchestration using the Truto MCP server.

Workflow 1: The FinOps Reconciliaton Audit

A Financial Operations engineer needs to identify stalled payments at the end of the month and force them to sync with the downstream processor (e.g., if a webhook failed to deliver).

"Scan the transaction list for any transactions from the past 24 hours that are in a 'pending' state. For each one you find, execute a sync to resolve the state with the gateway. Provide a final table of the original transaction IDs and their new resolved statuses."

Step-by-Step Breakdown:

1. Discovery: ChatGPT invokes list_all_spreedly_transactions with a high limit to pull the recent transaction ledger.
2. Analysis: The LLM parses the JSON array, filtering internally for records where state == "pending".
3. Execution Loop: For each matching record, the LLM extracts the token and invokes create_a_spreedly_transaction.
4. Formatting: The LLM receives the updated transaction states, compiles them into a markdown table, and presents the reconciled data back to the user.

sequenceDiagram
    participant User as FinOps Admin
    participant Agent as ChatGPT
    participant Truto as Truto MCP Server
    participant Spreedly as Spreedly API

    User->>Agent: "Find pending transactions and sync them"
    Agent->>Truto: call tools/call (list_all_spreedly_transactions)
    Truto->>Spreedly: GET /v1/transactions.json
    Spreedly-->>Truto: JSON Array
    Truto-->>Agent: Returns 3 pending transactions
    
    loop For each pending token
        Agent->>Truto: call tools/call (create_a_spreedly_transaction)
        Truto->>Spreedly: POST /v1/transactions/{token}/sync.json
        Spreedly-->>Truto: Resolved State (succeeded)
        Truto-->>Agent: State update success
    end

    Agent-->>User: Renders Markdown Table of resolved states

Workflow 2: Automated Support Refunds

A Customer Support Lead wants to refund a duplicate charge without leaving their interface or manually logging into the Spreedly vault.

"Find the transaction for 50 USD that occurred on gateway token GTokenABC. Once you locate it, retrieve its full details. If the status is 'succeeded', issue a refund for the transaction and confirm the gateway message."

Step-by-Step Breakdown:

1. Search: ChatGPT calls list_all_spreedly_gateway_transactions passing the specific gateway_token as an argument to scope the search.
2. Inspection: It identifies the correct transaction based on the amount and calls get_single_spreedly_transaction_by_id using the retrieved token to ensure the state is valid for refund.
3. Mutation: The LLM calls create_a_spreedly_refund, passing the transaction_token to initiate the credit.
4. Confirmation: The tool returns the updated state, and the LLM summarizes the successful refund, extracting the specific message returned by the payment processor.

The Strategic Shift to Agentic Payments

Integrating AI with payment orchestration is fundamentally different from read-only BI analytics. Payment environments are volatile. Endpoints timeout. Gateways enforce asynchronous rules.

By leveraging an architecture that dynamically maps documentation to MCP tools, you bypass the brittleness of hardcoded integrations. Truto's proxy handles the underlying API delegation, leaving the LLM to do what it does best: reason about logic, manage complex identifier relationships, and handle error states using natural language workflows.