How to connect GoCardless MCP with Python

Cancel a mandate. Also known as: stop a direct debit, revoke a mandate, cancel an authorisation. HIGH-BLAST-RADIUS operation — this also cancels everything attached to the mandate. Two-call pattern: first call with confirmed=false returns a preview enumerating what will be cancelled; second call with confirmed=true executes after the user has explicitly confirmed in their next message. DO NOT pass confirmed=true in the same turn as a preview. Requirements: - Mandate must be in a cancellable state: pending_customer_approval, pending_submission, submitted, or active. Mandates already cancelled, failed, expired, consumed, or blocked cannot be cancelled. - Cancellation is irreversible — once cancelled, the mandate cannot be reinstated and the payer would have to set up a new authorisation. Cascading side effects (will happen automatically): - All active subscriptions on this mandate auto-cancel. No further scheduled payments will be created. - All pending payments on this mandate auto-cancel (pending_customer_approval, pending_submission). Already-submitted payments continue through the bank. - All cancellable instalment schedules on this mandate auto-cancel. - The bank authorisation is revoked where the scheme supports it (Frontier-enabled schemes). The payer's bank will no longer permit collections. The preview enumerates active subscriptions and pending payments so the merchant can see the full blast radius before confirming. One of mandate_id (single) or mandate_ids (bulk) must be provided. Bulk cap: mandate_ids accepts up to 10 IDs per call. - If the user asks to cancel more than 10 mandates, do NOT call this tool multiple times to work around the cap. Instead: state the 10-per-call limit and ask the user to confirm a specific quantity to proceed with. Wait for their reply before proceeding. - When the requested count exceeds 10, process one batch at a time — preview and confirm the first batch, execute it, then preview and confirm the next batch. Do not preview subsequent batches before the previous one has been confirmed and created. Requires read_write scope.

Cancel a payment before it is submitted to the bank. Also known as: stop a payment, void a payment, withdraw a payment. Two-call pattern: first call with confirmed=false returns a preview; second call with confirmed=true executes after the user has explicitly confirmed in their next message. DO NOT pass confirmed=true in the same turn as a preview. Requirements: - Payment must be in a cancellable state: pending_customer_approval or pending_submission. Payments that are submitted, confirmed, paid_out, failed, cancelled, or charged_back cannot be cancelled. - Cancellation is irreversible — once cancelled, the payment cannot be reinstated. Important side effects (or lack thereof): - Cancelling a payment that belongs to a subscription does NOT cancel the subscription. The subscription will continue to generate future payments on its schedule. If the merchant wants to stop future payments, the subscription must be cancelled separately. - Cancellation does not affect the mandate; the mandate remains active. One of payment_id (single) or payment_ids (bulk) must be provided. Bulk cap: payment_ids accepts up to 10 IDs per call. - If the user asks to cancel more than 10 payments, do NOT call this tool multiple times to work around the cap. Instead: state the 10-per-call limit and ask the user to confirm a specific quantity to proceed with. Wait for their reply before proceeding. - When the requested count exceeds 10, process one batch at a time — preview and confirm the first batch, execute it, then preview and confirm the next batch. Do not preview subsequent batches before the previous one has been confirmed and created. Requires read_write scope.

Create a one-off payment against an existing mandate. Also known as: take a payment, charge a customer, collect a payment, debit a customer. Two-call pattern: first call with confirmed=false returns a preview; second call with confirmed=true executes after the user has explicitly confirmed in their next message. DO NOT pass confirmed=true in the same turn as a preview. Requirements: - Mandate must be in pending_submission, submitted, or active state. Inactive mandates (blocked, cancelled, expired, failed) will be rejected. - Payment currency MUST match the mandate's currency. - charge_date must respect the scheme's minimum working-days notice: - Bacs: 3 working days (default), 1 working day (absolute minimum). - SEPA Core, PAD, Autogiro, Betalingsservice: 1 working day. - Faster Payments, ACH, BECS, BECS_NZ: 0 working days (same-day OK). If charge_date is omitted, the mandate's next_possible_charge_date is used. - If the mandate has payments_require_approval=true, the payment will land in pending_customer_approval and won't be submitted to the bank until the payer approves. Bulk cap: count accepts up to 25 per call. - If the user asks for a specific number ≤ 25, pass it directly. - If the user asks for more than 25 (e.g. "create 100 payments"), do NOT call this tool multiple times to work around the cap. Instead: state the 25-per-call limit and ask the user to confirm a specific quantity to proceed with. Wait for their reply before proceeding. - If multiple batches are needed, process ONE batch per user reply — this means one preview call, then one confirm call, then report and wait. Do not call this tool more than once per user reply even for previews. Never pre-load multiple previews across batches before asking for approval. Requires read_write scope. Idempotency keys remain valid for 31 days.

Create a Billing Request — a single-use GoCardless-hosted authorisation link for one payer. Also known as: payment link, authorisation link, send a payment request. Note: this tool creates a GoCardless-hosted payment page. CPP merchants building their own payment UI should call the billing requests API with actions directly rather than using this tool. IMPORTANT: Any fixed payment amount on a Billing Request is collected via IBP (Instant Bank Pay) only — faster_payments, pay_to, or sepa_credit_transfer. Direct Debit does NOT support a one-off fixed amount within the BR flow itself. If a merchant asks to collect a one-off payment and does not specify IBP, ask which they prefer: - IBP (instant, settles in ~1 business day): use payment_only=true or the combined flow. - Direct Debit (3–5 days for Bacs, etc.): use mandate-only (no amount), then call create_payment once the mandate is active. This requires two steps — confirm the merchant is happy to wait. Do NOT assume IBP. Always clarify before proceeding if the collection method is ambiguous. Workflows (choose one): - Mandate-only (DD setup, charge later via create_payment): scheme only, no amount. Schemes: bacs, sepa_core, ach, pad, becs, becs_nz, autogiro, betalingsservice. - Payment-only / IBP (instant one-off, no mandate): scheme + amount + currency + payment_only=true. Schemes: faster_payments, pay_to, sepa_credit_transfer. - Combined (mandate + immediate IBP payment): scheme + amount + currency. Default IBP scheme is inferred from currency. To use a different IBP scheme for the payment than the mandate (e.g. bacs mandate + faster_payments payment), pass payment_request_scheme explicitly. - VRP consent (variable recurring payments, mandate-only on faster_payments): scheme=faster_payments + constraints_max_amount_per_payment + periodic_limit_period + periodic_limit_max_total_amount. For sVRP (sweeping between own accounts) also pass sweeping=true. For cVRP (merchant-initiated) also pass purpose_code, payment_context_code, and payment_purpose_code. Currency maps 1:1 to scheme: bacs/faster_payments=GBP, sepa_core/sepa_credit_transfer=EUR, ach=USD, pad=CAD, becs/pay_to=AUD, becs_nz=NZD, autogiro=SEK, betalingsservice=DKK. Use create_payment_link (this tool) when: the payer is a specific known customer, the merchant needs VRP (Variable Recurring Payments via faster_payments mandate scheme), or the merchant is building a CPP (Custom Payment Page) flow. Use create_payment_template_link instead when: the merchant wants a permanent reusable link to embed in a website or email for multiple customers (BRT does not support VRP). Do NOT ask for redirect_uri unless the merchant mentions a post-payment landing page. Returns an authorisation URL. Requires read_write scope.

Create a reusable Billing Request Template — a permanent shareable link that creates a new customer session each time it is visited. Also known as: payment template, reusable payment link, shareable payment page. Use this tool when the same link will be sent to more than one customer. Use create_payment_link instead if you need VRP, or want to pre-fill a specific returning customer's details. Key differences from create_payment_link: - Reusable: the same URL can be visited by unlimited customers; each visit creates a new session. - No specific customer at creation time — the customer provides their details when they visit the link. - Does NOT support VRP (Variable Recurring Payments). faster_payments cannot be used as a mandate scheme. - payment_request_scheme is limited to faster_payments, sepa_credit_transfer, sepa_instant_credit_transfer. pay_to is NOT available as a payment scheme on a BRT. - payment_request_amount is in full decimal form (e.g. "25.00"), not minor units. Workflows (choose one): - Mandate-only (DD setup only): mandate_request_scheme required; no payment fields. Schemes: bacs, sepa_core, ach, pad, becs, becs_nz, autogiro, betalingsservice, pay_to, sepa_credit_transfer. - Payment-only (one-off IBP payment, no mandate): payment_request_scheme + amount + currency; no mandate fields. Schemes: faster_payments, sepa_credit_transfer, sepa_instant_credit_transfer. - Combined (mandate + one-off IBP payment): both mandate and payment fields. Currency maps 1:1 to scheme: bacs=GBP, sepa_core/sepa_credit_transfer=EUR, ach=USD, pad=CAD, becs/pay_to=AUD, becs_nz=NZD, autogiro=SEK, betalingsservice=DKK, faster_payments=GBP. Returns a permanent authorisation URL. Requires read_write scope.

Refund all or part of a previously-collected payment back to the payer's bank account. Also known as: issue a refund, send money back, reverse a payment, reimburse a customer. Two-call pattern: first call with confirmed=false returns a preview; second call with confirmed=true executes after the user has explicitly confirmed in their next message. DO NOT pass confirmed=true in the same turn as a preview. Requirements: - Payment must be in a refundable state: confirmed or paid_out. Pending, failed, cancelled, or charged-back payments cannot be refunded. - amount is in minor units and must be > 0 and <= the payment's remaining refundable amount (payment.amount minus payment.amount_refunded). - Refunds are NOT reversible once submitted. Additional pay-svc constraints (will produce 422 if violated): - Safer-refund period: refunds are blocked for 7 days after the payment's charge_date unless the merchant has override permission. Trying to refund a very recent payment will fail — the merchant should wait, or use the GoCardless dashboard if they have refund-override permission. - Negative balance limit: refunds cannot push the creditor's payout balance below their configured negative-balance limit (typically 0). Large refunds against a low payout balance will fail. - Mandate-linked refunds (refunds without a specific payment_id) require the "Mandate refunds upgrade" on the organisation. This tool does not support that path — if the merchant needs it, direct them to the GoCardless dashboard. Currency is inherited from the payment. Reference is optional and shows on the payer's bank statement where supported (most schemes cap reference at 18 characters). One of payment_id (single) or payment_ids (bulk) must be provided. Bulk cap: payment_ids accepts up to 10 IDs per call. - If the user explicitly provides ≤ 10 IDs, pass them directly. - If the scope exceeds 10 (e.g. "refund all failed payments from last month"), do NOT loop or make multiple sequential calls to work around the cap. Instead: tell the user how many payments match, state the 10-per-call limit, and ask them to confirm which specific subset to process first. Wait for their reply before proceeding. - If multiple batches are needed, process ONE batch per user reply — this means one preview call, then one confirm call, then report and wait. Do not call this tool more than once per user reply even for previews. Never pre-load multiple previews across batches before asking for approval. Requires read_write scope. Idempotency keys remain valid for 31 days.

Create a recurring subscription against a mandate. Also known as: set up recurring payments, set up a direct debit, schedule regular payments. Two-call pattern: first call with confirmed=false returns a preview; second call with confirmed=true executes after the user has explicitly confirmed in their next message. DO NOT pass confirmed=true in the same turn as a preview. Supported schemes: bacs, sepa_core, ach, becs, becs_nz, betalingsservice, autogiro, pad, pay_to. IBP schemes do not support subscriptions: faster_payments, sepa_credit_transfer, sepa_instant_credit_transfer. Scheduling rules: - interval_unit=monthly: day_of_month required (1–28, or -1 for last day of month). - interval_unit=yearly: both month (e.g. january) and day_of_month required. - interval_unit=weekly: day_of_month and month must not be set. - interval defaults to 1 if omitted. - start_date must be on or after the mandate's next_possible_charge_date. Defaults to next_possible_charge_date if omitted. payment_reference for Bacs: requires own Service User Number; the mandate reference + dash + payment_reference must be ≤ 18 characters combined. retry_if_possible: requires Success+ to be enabled in the GoCardless dashboard. Bulk cap: mandate_ids accepts up to 25 IDs per call (creates the same subscription config for each mandate). - If the user asks to create subscriptions for more than 25 mandates, do NOT call this tool multiple times to work around the cap. Instead: state the 25-per-call limit and ask the user to confirm a specific quantity to proceed with. Wait for their reply before proceeding. - When the requested count exceeds 25, process one batch at a time — preview and confirm the first batch, execute it, then preview and confirm the next batch. Do not preview subsequent batches before the previous one has been confirmed and created. Requires read_write scope. Idempotency keys remain valid for 31 days.

Retrieve a single customer by ID. PII fields are partially masked. Use when you have a known customer ID (CU…). To search or list multiple customers, use list_customers.

Returns the current GoCardless environment (sandbox or live) and step-by-step instructions for switching. Use this when the user asks which environment they are in, wants to switch to live, wants to switch to sandbox, or seems confused about whether they are looking at real or test data.

Retrieve a single mandate (Direct Debit authorisation) by ID. Use when you have a known mandate ID (MD…). To search or filter across mandates, use list_mandates.

Retrieve a single payment by ID. Use when you have a known payment ID (PM…). To search or filter across multiple payments, use list_payments.

Get the count and total amount of payments in a date range, optionally filtered by status, customer, mandate, subscription, or currency. The total is net of any refunds, with the refunded amount also broken out separately. Use this instead of list_payments whenever the question needs a total, count, average, or "how much"/"how many" across multiple payments — never page through list_payments yourself and sum the results. Requires at least one date range: created_at_gte/created_at_lte, charge_date_gte/charge_date_lte, or both together (both narrows to payments matching both ranges - e.g. "payments created this week that are due to be collected next week"). For a single-axis question, use charge_date for when money actually moved ("how much did I collect in June") — created_at can be days earlier than charge_date for payments created under an advance notice period, so it can include or exclude the wrong payments for that kind of question. Use created_at on its own only when the question is specifically about when payments were set up/created, not collected.

Retrieve a single payout (settlement to your bank account) by ID. Use when you have a known payout ID (PO…). To search or filter across payouts, use list_payouts.

Retrieve a single refund by ID. Use when you have a known refund ID (RF…). To search or filter across refunds, use list_refunds.

Retrieve a single subscription (recurring payment schedule) by ID. Use when you have a known subscription ID (SB…). To search or filter across subscriptions, use list_subscriptions.

Returns an overview of GoCardless integration options for collecting one-off and recurring bank payments. This tool returns an overview only — you MUST then call read_gocardless_resource with the relevant URI from the overview before answering the user's question.

List customers, optionally filtered by creation date. PII fields are partially masked. For a single known customer ID, use get_customer.

Audit log of state changes across all resources (e.g. payment confirmed, mandate cancelled). Use for audit trails and webhook debugging. Not for querying amounts or counts — use list_payments for that. Note: data older than 18 months may not be available.

Search or filter mandates (Direct Debit authorisations) by status, customer, or scheme. For a single known mandate ID, use get_mandate.

Search, filter, or count payments by status, customer, mandate, subscription, currency, or date range. Use for any multi-record query. For a single known payment ID, use get_payment.

Search or filter payouts (settlements to your bank account) by status, currency, or date range. For a single known payout ID, use get_payout.

Search or filter refunds by payment, mandate, or date range. For a single known refund ID, use get_refund.

Search or filter subscriptions (recurring payment schedules) by status, customer, or mandate. For a single known subscription ID, use get_subscription.

Serves GoCardless API documentation, how-to guides, and code samples — not live account data. Use this to fetch API endpoint details, integration guides, and code samples. Available URIs: - gocardless://api/endpoints — list of all API endpoints - gocardless://api/endpoints/{name} — details of a specific endpoint - gocardless://api/code_samples/{language} — all code samples for a language (java, python, ruby, dotnet, php, go, javascript, http) - gocardless://api/code_samples/{language}/{endpoint} — code samples for a specific endpoint in a language - gocardless://how_to/collect_one-off_payments - gocardless://how_to/collect_recurring_payments - gocardless://how_to/create_reusable_payment_templates - gocardless://how_to/handle_webhooks - gocardless://how_to/use_billing_request_with_actions - gocardless://how_to/use_custom_payment_pages - gocardless://how_to/use_gocardless_components

Submit a rating (1–5) of how helpful this MCP session was. Call this at the end of a session when the user expresses satisfaction or dissatisfaction, or when they explicitly ask to leave feedback.

Update an existing subscription: change its amount, name, payment reference, metadata or retry setting. Also known as: change a subscription amount, edit a subscription, reduce or increase a subscription. Two-call pattern: first call with confirmed=false returns a before → after preview; second call with confirmed=true executes after the user has explicitly confirmed in their next message. DO NOT pass confirmed=true in the same turn as a preview. Requirements: - id and at least one of amount, name, payment_reference, metadata, retry_if_possible. - The subscription must be active (not paused, cancelled or finished) and must not have taken its final payment. - Amount changes: the amount can only be changed 10 times per subscription, and is not allowed on mandates that require customer approval for payments. Only the app that created a subscription can change its amount, so subscriptions created in the dashboard or via another integration cannot be updated here, only ones created through this MCP. - amount is in minor units (e.g. 9500 for £95.00). metadata replaces the whole metadata object. retry_if_possible can only be switched on. Requires read_write scope.