GoCardless MCP

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'gocardlessmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize GoCardless MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'gocardlessmcp_get_environment',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "gocardlessmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize GoCardless MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="gocardlessmcp_get_environment",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Create subscription, refund, payment template link — Create a recurring subscription against a mandate, scheduling regular payments on a weekly, monthly, or yearly interval
• Payment cancel — Cancel a payment before it is submitted to the bank
• Mandate cancel — Cancel a mandate (Direct Debit authorisation)
• Feedback submit — Submit a helpfulness rating (1–5) for the current MCP session, with an optional comment
• Read gocardless resource — Read the contents of a GoCardless resource by URI to fetch API endpoint details or documentation
• List subscriptions, refunds, payouts — List subscriptions (recurring payment schedules), optionally filtered by status, customer, or mandate

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

gocardlessmcp_cancel_mandate#Cancel a mandate (Direct Debit authorisation). This also auto-cancels any active subscriptions and pending payments attached to the mandate. Irreversible once cancelled.4 params▾

Cancel a mandate (Direct Debit authorisation). This also auto-cancels any active subscriptions and pending payments attached to the mandate. Irreversible once cancelled.

NameTypeRequiredDescription

confirmedbooleanoptionalSet true only after the user has explicitly confirmed the preview in their most recent message. Default false (returns a preview).

mandate_idstringoptionalID of the mandate to cancel (e.g. MD000123). Must be in a cancellable state — see description.

mandate_idsarrayoptionalFor bulk cancellations: list of mandate IDs to cancel (max 10). Use instead of mandate_id.

preview_tokenstringoptionalRequired when confirmed=true: the preview_token field from this tool's own preceding preview response (the confirmed=false call for these exact same parameters). Rejected if missing, mismatched, already used, or if confirmed=true arrives too soon after the preview — a preview_token is only valid a few seconds after being issued, since it exists to prove a genuine user reply happened in between, not just that a preview call was made. If confirmed=true is rejected for being too soon, wait for the user's actual next message before trying again; do not immediately retry.

gocardlessmcp_cancel_payment#Cancel a payment before it is submitted to the bank. Only payments in pending_customer_approval or pending_submission state can be cancelled. Irreversible once cancelled.4 params▾

Cancel a payment before it is submitted to the bank. Only payments in pending_customer_approval or pending_submission state can be cancelled. Irreversible once cancelled.

NameTypeRequiredDescription

confirmedbooleanoptionalSet true only after the user has explicitly confirmed the preview in their most recent message. Default false (returns a preview).

payment_idstringoptionalID of the payment to cancel (e.g. PM000123). Must be in pending_customer_approval or pending_submission state.

payment_idsarrayoptionalFor bulk cancellations: list of payment IDs to cancel (max 10). Use instead of payment_id.

preview_tokenstringoptionalRequired when confirmed=true: the preview_token field from this tool's own preceding preview response (the confirmed=false call for these exact same parameters). Rejected if missing, mismatched, already used, or if confirmed=true arrives too soon after the preview — a preview_token is only valid a few seconds after being issued, since it exists to prove a genuine user reply happened in between, not just that a preview call was made. If confirmed=true is rejected for being too soon, wait for the user's actual next message before trying again; do not immediately retry.

gocardlessmcp_create_payment#Create a one-off payment against an existing mandate. The mandate must be active or pending submission, and the payment currency must match the mandate's currency.11 params▾

Create a one-off payment against an existing mandate. The mandate must be active or pending submission, and the payment currency must match the mandate's currency.

NameTypeRequiredDescription

amountnumberrequiredAmount in minor units (e.g. pence for GBP, cents for USD).

currencystringrequiredISO 4217 currency code. Must match the mandate's currency.

mandate_idstringrequiredID of the mandate to charge (e.g. MD000123). Must be in pending_submission, submitted, or active state.

charge_datestringoptionalOptional charge date (YYYY-MM-DD). Omit to use the next possible charge date for the mandate.

confirmedbooleanoptionalSet true only after the user has explicitly confirmed the preview in their most recent message. Default false (returns a preview).

countnumberoptionalNumber of identical payments to create against the same mandate (max 25, default 1). When >1, returns a bulk preview before executing.

descriptionstringoptionalOptional name for the payment shown in the GoCardless dashboard and on payer confirmation emails. Helps merchants and payers identify the payment (e.g. "Admin fee", "Invoice 123").

faster_achbooleanoptionalACH only. Set true to explicitly use Faster ACH, false for standard ACH. Omit to let the presence or absence of charge_date determine the processing speed.

preview_tokenstringoptionalRequired when confirmed=true: the preview_token field from this tool's own preceding preview response (the confirmed=false call for these exact same parameters). Rejected if missing, mismatched, already used, or if confirmed=true arrives too soon after the preview — a preview_token is only valid a few seconds after being issued, since it exists to prove a genuine user reply happened in between, not just that a preview call was made. If confirmed=true is rejected for being too soon, wait for the user's actual next message before trying again; do not immediately retry.

referencestringoptionalCustom bank statement reference. Scheme-specific length limits apply (e.g. 10 chars for Bacs, 140 for SEPA). Not supported for Faster Payments. Bacs custom references require GoCardless Plus/Pro/Enterprise.

retry_if_possiblebooleanoptionalAutomatically retry the payment on failure using intelligent retries. Requires Success+ to be enabled in the GoCardless dashboard. Default false.

gocardlessmcp_create_payment_link#Create a Billing Request — a single-use GoCardless-hosted authorisation link for a specific payer, supporting mandate setup, one-off IBP payments, or VRP consent.21 params▾

Create a Billing Request — a single-use GoCardless-hosted authorisation link for a specific payer, supporting mandate setup, one-off IBP payments, or VRP consent.

NameTypeRequiredDescription

schemestringrequiredPayment scheme for the mandate (or for IBP when payment_only=true). Examples: faster_payments, bacs, sepa_core, ach, pad, becs, pay_to.

amountnumberoptionalAmount in minor units (e.g. pence for GBP). Required when payment_only=true.

constraints_end_datestringoptionalLatest date by which payments can be taken (YYYY-MM-DD). Leave unset for an open-ended agreement.

constraints_max_amount_per_paymentnumberoptionalMaximum amount in minor units that can be charged per payment. Required for PayTo and VRP mandates.

constraints_start_datestringoptionalEarliest date from which payments can be taken (YYYY-MM-DD). Defaults to the day the payer authorises.

currencystringoptionalISO 4217 currency code. Required when amount is set.

customer_bank_account_idstringoptionalExisting GoCardless customer bank account ID to pre-fill, skipping the bank account collection step.

customer_idstringoptionalExisting GoCardless customer ID to link, optional.

descriptionstringoptionalDescription shown to the payer during authorisation.

fallback_enabledbooleanoptionalIf true, the billing request can fall back to Direct Debit if the payer's bank does not support the requested scheme (IBP or VRP). Applies to both IBP payment requests and VRP mandate requests. Do not set if GoCardless payment intelligence is enabled.

mandate_verifystringoptionalVerification preference for the mandate: minimum, recommended (default), when_available, or always.

payment_context_codestringoptionalPayment context for cVRP mandates. One of: billing_goods_and_services_in_advance, billing_goods_and_services_in_arrears, pisp_payee, ecommerce_merchant_initiated_payment, face_to_face_point_of_sale, transfer_to_self, transfer_to_third_party, bill_payment, ecommerce_goods, ecommerce_services, other, party_to_party. Required for cVRP.

payment_onlybooleanoptionalSet true for a payment-only (IBP) flow — no mandate will be created. Requires amount and currency.

payment_purpose_codestringoptionalUnderlying payment purpose for cVRP mandates (e.g. loan_repayment, bank_loan_delayed_draw_funding, salary_payment). See VRP Commercial Payment Purpose Codes for the full list. Required for cVRP.

payment_request_schemestringoptionalOverride the IBP scheme used for the payment_request in a combined flow. Omit to let the API infer from currency. Only valid when amount is set and payment_only=false.

periodic_limit_alignmentstringoptionalHow the period resets: calendar (end of current period, e.g. end of month) or creation_date (same date next period). Defaults to creation_date.

periodic_limit_max_total_amountnumberoptionalMaximum total amount in minor units that can be charged within the periodic_limit_period. Required for VRP mandates.

periodic_limit_periodstringoptionalPeriod for the VRP periodic limit. One of: intraday, day, week, fortnight, month, quarter, half_year, year, flexible. Required when setting a periodic limit.

purpose_codestringoptionalHigh-level purpose category for the mandate and/or payment. Common values: loan, salary_payment, supplier_payment, tax_payment, commercial, consumer, dividend, pension_payment. See Billing Request Purpose Codes for the full list.

redirect_uristringoptionalURL to redirect the payer to after they complete the GoCardless-hosted flow. This is the post-flow landing page — not the bank authorisation redirect used in CPP flows. Omit to use the GoCardless default success screen.

sweepingbooleanoptionalSet true for sVRP (Sweeping VRP) — money moved between accounts owned by the same payer. Only valid for faster_payments mandate-only flows; do not combine with payment_only=true.

gocardlessmcp_create_payment_template_link#Create a reusable Billing Request Template — a permanent shareable link that can be sent to multiple customers, each visit creating a new authorisation session.11 params▾

Create a reusable Billing Request Template — a permanent shareable link that can be sent to multiple customers, each visit creating a new authorisation session.

NameTypeRequiredDescription

namestringrequiredName for this template shown in the dashboard (max 255 chars).

mandate_request_currencystringoptionalISO 4217 currency code for the mandate (e.g. GBP, EUR). Usually inferred from scheme.

mandate_request_descriptionstringoptionalDescription shown to the customer during mandate setup.

mandate_request_schemestringoptionalScheme for the mandate. Supported: bacs, sepa_core, ach, pad, becs, becs_nz, autogiro, betalingsservice, pay_to, sepa_credit_transfer. Note: faster_payments is blocked (use create_payment_link for VRP).

mandate_request_verifystringoptionalVerification preference for the mandate: minimum, recommended (default), when_available, or always.

metadataobjectoptionalKey-value store of custom data for the template. Up to 3 keys, key names up to 50 chars, values up to 500 chars.

payment_request_amountstringoptionalAmount for the one-off payment in full decimal form (e.g. "25.00"), NOT minor units. Required when payment_request_scheme is set.

payment_request_currencystringoptionalISO 4217 currency code for the one-off payment. Required when payment_request_amount is set.

payment_request_descriptionstringoptionalDescription shown to the customer during payment authorisation.

payment_request_schemestringoptionalScheme for the one-off payment. Limited to: faster_payments, sepa_credit_transfer, sepa_instant_credit_transfer. pay_to is not supported.

redirect_uristringoptionalURL to redirect the customer to after they complete the flow. Omit to use the GoCardless default success screen.

gocardlessmcp_create_refund#Refund all or part of a previously-collected payment back to the payer's bank account. The payment must be in a refundable state (confirmed or paid_out).7 params▾

Refund all or part of a previously-collected payment back to the payer's bank account. The payment must be in a refundable state (confirmed or paid_out).

NameTypeRequiredDescription

amountnumberrequiredRefund amount in minor units (e.g. pence for GBP). Must be <= the payment's remaining refundable amount.

confirmedbooleanoptionalSet true only after the user has explicitly confirmed the preview in their most recent message. Default false (returns a preview).

metadataobjectoptionalKey-value store of custom data attached to the refund. Up to 3 keys, key names up to 50 chars, values up to 500 chars.

payment_idstringoptionalID of the payment to refund (e.g. PM000123). Must be in confirmed or paid_out status.

payment_idsarrayoptionalFor bulk refunds: list of payment IDs to refund (max 10). Each gets the same amount. Use instead of payment_id.

preview_tokenstringoptionalRequired when confirmed=true: the preview_token field from this tool's own preceding preview response (the confirmed=false call for these exact same parameters). Rejected if missing, mismatched, already used, or if confirmed=true arrives too soon after the preview — a preview_token is only valid a few seconds after being issued, since it exists to prove a genuine user reply happened in between, not just that a preview call was made. If confirmed=true is rejected for being too soon, wait for the user's actual next message before trying again; do not immediately retry.

referencestringoptionalOptional reference shown on the payer's bank statement where supported (max 18 chars for most schemes).

gocardlessmcp_create_subscription#Create a recurring subscription against a mandate, scheduling regular payments on a weekly, monthly, or yearly interval.16 params▾

Create a recurring subscription against a mandate, scheduling regular payments on a weekly, monthly, or yearly interval.

NameTypeRequiredDescription

amountnumberrequiredAmount per payment in minor units (e.g. pence for GBP, cents for EUR).

currencystringrequiredISO 4217 currency code (e.g. GBP, EUR, USD). Must match the mandate's scheme.

interval_unitstringrequiredTime unit between charges: weekly, monthly, or yearly.

confirmedbooleanoptionalSet true only after the user has explicitly confirmed the preview in their most recent message. Default false (returns a preview).

countnumberoptionalTotal number of payments to take. Omit (or set 0) for an indefinite subscription.

day_of_monthnumberoptionalDay of month to charge (1–28, or -1 for last day). Required for monthly and yearly subscriptions.

intervalnumberoptionalNumber of interval_units between charges. Must be ≥ 1. Defaults to 1.

mandate_idstringoptionalID of the mandate to create the subscription against (e.g. MD000123).

mandate_idsarrayoptionalFor bulk creation: list of mandate IDs to create the subscription against (max 25). Use instead of mandate_id.

metadataobjectoptionalKey-value store of custom data. Up to 3 keys, key names up to 50 chars, values up to 500 chars.

monthstringoptionalMonth to charge, lowercase (e.g. january). Required for yearly subscriptions.

namestringoptionalName for the subscription (max 255 chars). Used as the description on each payment created.

payment_referencestringoptionalReference shown on the customer's bank statement. For Bacs: requires own Service User Number.

preview_tokenstringoptionalRequired when confirmed=true: the preview_token field from this tool's own preceding preview response (the confirmed=false call for these exact same parameters). Rejected if missing, mismatched, already used, or if confirmed=true arrives too soon after the preview — a preview_token is only valid a few seconds after being issued, since it exists to prove a genuine user reply happened in between, not just that a preview call was made. If confirmed=true is rejected for being too soon, wait for the user's actual next message before trying again; do not immediately retry.

retry_if_possiblebooleanoptionalRetry failed payments using intelligent retries (Success+). Defaults to false. Requires Success+ enabled in the GoCardless dashboard.

start_datestringoptionalDate of the first payment (YYYY-MM-DD). Must be on or after the mandate's next_possible_charge_date. Defaults to next_possible_charge_date if omitted.

gocardlessmcp_get_customer#Retrieve a single customer by ID, with PII fields partially masked.1 param▾

Retrieve a single customer by ID, with PII fields partially masked.

NameTypeRequiredDescription

idstringrequiredCustomer ID (e.g. CU000123)

gocardlessmcp_get_environment#Return the current GoCardless environment (sandbox or live) and setup instructions.0 params▾

Return the current GoCardless environment (sandbox or live) and setup instructions.

gocardlessmcp_get_mandate#Retrieve a single mandate (Direct Debit authorisation) by its mandate ID.1 param▾

Retrieve a single mandate (Direct Debit authorisation) by its mandate ID.

NameTypeRequiredDescription

idstringrequiredMandate ID (e.g. MD000123)

gocardlessmcp_get_payment#Retrieve a single payment by its payment ID.1 param▾

Retrieve a single payment by its payment ID.

NameTypeRequiredDescription

idstringrequiredPayment ID (e.g. PM000123)

gocardlessmcp_get_payout#Retrieve a single payout (bank settlement) by its payout ID.1 param▾

Retrieve a single payout (bank settlement) by its payout ID.

NameTypeRequiredDescription

idstringrequiredPayout ID (e.g. PO000123)

gocardlessmcp_get_refund#Retrieve a single refund by its refund ID.1 param▾

Retrieve a single refund by its refund ID.

NameTypeRequiredDescription

idstringrequiredRefund ID (e.g. RF000123)

gocardlessmcp_get_subscription#Retrieve a single subscription (recurring payment schedule) by its subscription ID.1 param▾

Retrieve a single subscription (recurring payment schedule) by its subscription ID.

NameTypeRequiredDescription

idstringrequiredSubscription ID (e.g. SB000123)

gocardlessmcp_integrate_with_gocardless#Return an overview of GoCardless integration options for collecting one-off and recurring payments.0 params▾

Return an overview of GoCardless integration options for collecting one-off and recurring payments.

gocardlessmcp_list_customers#List customers, optionally filtered by creation date range.5 params▾

List customers, optionally filtered by creation date range.

NameTypeRequiredDescription

afterstringoptionalCursor for next page

created_at_gtestringoptionalFilter: created at or after this ISO 8601 datetime

created_at_ltestringoptionalFilter: created at or before this ISO 8601 datetime

limitnumberoptionalNumber of results per page (default 50, max 500)

sort_directionstringoptionalSort direction: asc or desc

gocardlessmcp_list_events#List audit log events for state changes across all resources, optionally filtered by resource type, action, or date range.11 params▾

List audit log events for state changes across all resources, optionally filtered by resource type, action, or date range.

NameTypeRequiredDescription

actionstringoptionalFilter by action (e.g. created, confirmed, failed, paid_out, cancelled)

afterstringoptionalCursor for next page

created_at_gtestringoptionalFilter: created at or after this ISO 8601 datetime

created_at_ltestringoptionalFilter: created at or before this ISO 8601 datetime

limitnumberoptionalNumber of results per page (default 50, max 500)

mandatestringoptionalFilter by mandate ID

paymentstringoptionalFilter by payment ID

payoutstringoptionalFilter by payout ID

refundstringoptionalFilter by refund ID

resource_typestringoptionalFilter by resource type: payments, mandates, payouts, refunds, subscriptions, instalment_schedules

subscriptionstringoptionalFilter by subscription ID

gocardlessmcp_list_mandates#List mandates (Direct Debit authorisations), optionally filtered by status, customer, or scheme.5 params▾

List mandates (Direct Debit authorisations), optionally filtered by status, customer, or scheme.

NameTypeRequiredDescription

afterstringoptionalCursor for next page

customerstringoptionalFilter by customer ID

limitnumberoptionalNumber of results per page (default 50, max 500)

schemestringoptionalFilter by scheme: bacs, sepa_core, ach, autogiro, becs, becs_nz, betalingsservice, faster_payments, pad, pay_to

statusstringoptionalFilter by status: pending_customer_approval, pending_submission, submitted, active, suspended_by_payer, failed, cancelled, expired, consumed, blocked

gocardlessmcp_list_payments#List payments, optionally filtered by status, customer, mandate, subscription, currency, or date range.10 params▾

List payments, optionally filtered by status, customer, mandate, subscription, currency, or date range.

NameTypeRequiredDescription

afterstringoptionalCursor for next page (from previous response's next_cursor)

created_at_gtestringoptionalFilter: created at or after this ISO 8601 datetime

created_at_ltestringoptionalFilter: created at or before this ISO 8601 datetime

currencystringoptionalFilter by currency code (e.g. GBP, EUR, USD)

customerstringoptionalFilter by customer ID (e.g. CU000123)

limitnumberoptionalNumber of results per page (default 50, max 500)

mandatestringoptionalFilter by mandate ID (e.g. MD000123)

sort_directionstringoptionalSort direction: asc or desc

statusstringoptionalFilter by status: pending_submission, submitted, confirmed, paid_out, cancelled, customer_approval_denied, failed, charged_back

subscriptionstringoptionalFilter by subscription ID (e.g. SB000123)

gocardlessmcp_list_payouts#List payouts (bank settlements), optionally filtered by status, currency, or date range.6 params▾

List payouts (bank settlements), optionally filtered by status, currency, or date range.

NameTypeRequiredDescription

afterstringoptionalCursor for next page

created_at_gtestringoptionalFilter: created at or after this ISO 8601 datetime

created_at_ltestringoptionalFilter: created at or before this ISO 8601 datetime

currencystringoptionalFilter by currency code (e.g. GBP, EUR, USD)

limitnumberoptionalNumber of results per page (default 50, max 500)

statusstringoptionalFilter by status: pending, paid, bounced

gocardlessmcp_list_refunds#List refunds, optionally filtered by payment, mandate, or date range.6 params▾

List refunds, optionally filtered by payment, mandate, or date range.

NameTypeRequiredDescription

afterstringoptionalCursor for next page

created_at_gtestringoptionalFilter: created at or after this ISO 8601 datetime

created_at_ltestringoptionalFilter: created at or before this ISO 8601 datetime

limitnumberoptionalNumber of results per page (default 50, max 500)

mandatestringoptionalFilter by mandate ID

paymentstringoptionalFilter by payment ID

gocardlessmcp_list_subscriptions#List subscriptions (recurring payment schedules), optionally filtered by status, customer, or mandate.5 params▾

List subscriptions (recurring payment schedules), optionally filtered by status, customer, or mandate.

NameTypeRequiredDescription

afterstringoptionalCursor for next page

customerstringoptionalFilter by customer ID

limitnumberoptionalNumber of results per page (default 50, max 500)

mandatestringoptionalFilter by mandate ID

statusstringoptionalFilter by status: pending_customer_approval, active, cancelled, finished, paused

gocardlessmcp_read_gocardless_resource#Read the contents of a GoCardless resource by URI to fetch API endpoint details or documentation.1 param▾

Read the contents of a GoCardless resource by URI to fetch API endpoint details or documentation.

NameTypeRequiredDescription

uristringrequiredThe gocardless:// resource URI to read

gocardlessmcp_submit_feedback#Submit a helpfulness rating (1–5) for the current MCP session, with an optional comment.2 params▾

Submit a helpfulness rating (1–5) for the current MCP session, with an optional comment.

NameTypeRequiredDescription

ratingnumberrequiredHow helpful was this session? 1 = not helpful at all, 5 = extremely helpful

commentstringoptionalOptional additional feedback