Your agent needs to work with GoCardless. It needs to pull failed payments, explain why a mandate lapsed, maybe issue a refund. GoCardless shipped an MCP server in February 2026 and has run a REST API for over a decade. Both paths work, and both are officially supported. But the MCP was built for a merchant sitting in front of Claude, and the API was built for software running unattended. That difference shows up in three places that decide your architecture: what the tools can do, how long a session lives, and whether the agent can retry safely.
These are two different products with overlapping surfaces, not two transports over the same capability set. Establishing what each one is takes a minute and saves an architecture rewrite later.
GoCardless announced its Model Context Protocol (MCP) server on 18 February 2026. It is a remote hosted endpoint at mcp.gocardless.com; there is nothing to install, and clients connect over streamable HTTP. Authentication is a browser sign-in journey where the merchant picks an environment (Sandbox or Live) and then selects which permissions to grant.
The server bundles two capabilities that are usually separate products. The first is integration guidance: your LLM can query GoCardless endpoint documentation, integration patterns, and code samples through gocardlessmcp_read_gocardless_resource and gocardlessmcp_integrate_with_gocardless. The second is account access: reading and acting on live payments, mandates, subscriptions, payouts, refunds, and events. It launched read-only and gained write capability later in 2026.
Official documentation: GoCardless MCP developer resources.
The REST API is a versioned JSON interface at api.gocardless.com for Live and api-sandbox.gocardless.com for Sandbox. Every request carries a bearer token in the Authorization header and a required GoCardless-Version header; the current version is 2015-07-06. PATCH is not supported, so updates use PUT.
The published reference covers 137 endpoints across 46 resource groups, spanning Billing Requests, Core objects, Payments, Mandates, Banking, Outbound Payments, Configuration, and Scenario Simulators. Two auth models exist: a dashboard-issued access token for your own account, and OAuth 2.0 (RFC 6749) for acting on behalf of other merchants' accounts.
Official documentation: GoCardless API Reference.
The MCP tool surface is deliberately narrow. It covers the operations a merchant would perform from the dashboard on a normal day, and stops there. The REST API covers everything the platform does.
The last row is not a rounding error. There is no REST endpoint that answers "how do I collect a joining fee plus a monthly membership fee". The MCP's documentation half genuinely has no API equivalent, and for a coding agent building a GoCardless integration it is the better tool by a wide margin.
PII masking is the second real win. Email addresses, phone numbers, and bank details are masked before the model sees them, and gocardlessmcp_get_customer returns partially masked fields by design. If your threat model includes payer data reaching a model provider, the MCP has already made that decision for you.
The absence of webhook tools reshapes event-driven designs. An MCP-driven agent has list_events and nothing else, so it polls. It cannot register a webhook endpoint, inspect delivery state, or retry a failed delivery. Those are REST-only operations.
Customer creation is also absent from the MCP. Worth noting for fairness: the API restricts it too. For OAuth apps, customer creation, customer bank account creation, and mandate creation are all restricted unless your payment pages are approved as scheme-rules compliant. Creditor management is restricted unconditionally.
This one is worth naming precisely because it looks like a small gap and behaves like a large one. The MCP can create a subscription and read it. It cannot pause, resume, update, or cancel one.
A customer asks to pause their gym membership for two months. On the REST API, that is a pause operation on the subscription. On the MCP, the only lever that stops charges is gocardlessmcp_cancel_mandate, and its own description states that cancelling a mandate auto-cancels every active subscription and pending payment attached to it, irreversibly. That is not a workaround; it is a different outcome.
Both paths are OAuth. They are not the same OAuth, and the difference is about session lifetime rather than protocol.
The MCP connects through a GoCardless sign-in journey. The identity is a dashboard user, not an application, and that user's dashboard role governs what the tools can do. A user with read-only dashboard permissions cannot create a payment through the MCP regardless of what they granted at consent time.
Then there is the clock. GoCardless states that read-write MCP access requires re-authentication every two weeks, and read-only access once a month. GoCardless presents this as a relaxation from a shorter previous window, and for an assistant it is invisible. For a background agent it is a recurring, unavoidable interactive step.
Sandbox or Live is chosen during the sign-in journey and fixed for the life of that connection. Switching means disconnecting and reconnecting, which is why the server ships a gocardlessmcp_get_environment tool at all: the agent has to ask which world it is in, because there is no per-request environment parameter to set. A single connected account cannot straddle test and production.
The OAuth path for the API runs through connect.gocardless.com. Your app is issued a client_id and client_secret, the merchant authorises, and you exchange an authorisation code (valid for 5 minutes) for an access token at POST /oauth/access_token.
That token is permanent. GoCardless documents no expiry and no refresh token; the response carries access_token, scope, token_type, organisation_id, and email. Reconnecting issues a new token and disables the previous one. You revoke through POST /oauth/revoke (RFC 7009) and validate through POST /oauth/introspect (RFC 7662).
The tradeoff is granularity. GoCardless defines exactly two OAuth scopes: read_only and read_write. There is no "refunds but not cancellations" scope and no per-resource scoping.
Least privilege at the OAuth layer is therefore a binary choice, and every finer control has to be enforced above it, in your own authorisation logic or at the tool layer.
Line these up and the decision usually makes itself. An MCP connection is a merchant user's session that expires on a fortnightly cadence and must be renewed in a browser. An API OAuth grant is an organisation-scoped token that persists until someone revokes it, and returns an organisation_id you use to route incoming webhook events to the right tenant.
For an agent serving 200 merchant organisations, the MCP path means 200 users receiving a re-auth prompt roughly twice a month, with agent runs silently stalling in between. The API path means 200 permanent tokens, 1,000 requests per minute of headroom per merchant, and revocation you control programmatically. This is the core challenge of multi-tenant tool calling agent auth, where session management strategy fundamentally changes between single and multi-tenant deployments.
This is the control that most cleanly separates an assistant from an automation, and it is worth understanding exactly rather than approximately.
Five MCP tools take a confirmed boolean and a preview_token. Calling with confirmed=false returns a preview plus a token. Calling with confirmed=true requires that token, for those exact same parameters.
The schema is explicit about why the token can be refused. It is rejected if missing, mismatched, already used, or if the confirm arrives too soon after the preview, because the delay exists to prove a genuine user reply happened in between rather than just that a preview call was made. The schema instructs the caller to wait for the user's actual next message and not to retry immediately.
Read that as an architectural statement. GoCardless has built a control that specifically defeats an unattended confirm loop.
The gate covers gocardlessmcp_create_payment, gocardlessmcp_create_refund, gocardlessmcp_create_subscription, gocardlessmcp_cancel_payment, and gocardlessmcp_cancel_mandate.
It does not cover the two link-creation tools. gocardlessmcp_create_payment_link mints a single-use Billing Request, including VRP consent with periodic limits, and gocardlessmcp_create_payment_template_link mints a permanent reusable link that starts a new authorisation session on every visit. Neither takes confirmed or preview_token. The rationale is presumably that a link does not move money until a payer authorises it, but a reusable template link is still a durable artifact your agent can create without a second turn. Design your prompts accordingly.
The REST API accepts an Idempotency-Key header on resource creation. Keys are capped at 128 characters, GoCardless recommends UUIDv4, and they are honoured for at least 30 days. A duplicate returns 409 idempotent_creation_conflict with links.conflicting_resource_id pointing at the resource that already exists. The documentation is blunt about why: retrying a payment creation after a network timeout without a key can take the same payment twice.
None of the 24 MCP tool schemas expose that header. The single-use preview_token blocks an accidental double-submit inside one conversation, which is a real protection, but it is a different guarantee.
Consider the failure that idempotency keys exist for. Your process sends the confirm and dies before reading the response. Did the refund happen?
On the API you replay the same key and get a 409 carrying the existing resource ID, which answers the question definitively. On the MCP you have no key to replay, so recovery means listing payments and reconciling by amount, mandate, and timestamp.
Recommended Reading: How to Handle Token Refresh for AI Agents and the broader patterns around agent tool calling auth in production.
Most engineers evaluating an MCP server never open its terms. For a payments MCP, that is a mistake, because the terms constrain the architecture as directly as the tool schemas do. What follows is a factual reading of the published Live Access terms, last updated 20 April 2026, not legal advice; route it past your counsel before you commit.
Clause 4.1.5 states that you agree not to use the MCP or MCP Data to process or handle any personal data. That sits alongside clause 8, which treats both parties as independent Data Controllers for personal data processed under the terms. The two clauses are in visible tension, and resolving that tension is a legal question rather than an engineering one.
Clause 4.2.4 pushes an obligation down your stack. You must procure that your AI service provider deletes and destroys MCP Data from its servers once it has been incorporated into an output, and certifies that it has done so. Clause 4.2.2 separately prohibits using MCP Data to train or improve models. If your model provider contract does not already cover both, that is a gap you own.
Clause 9.5 caps GoCardless's total aggregate liability under the MCP terms at £50. Clause 3.3 states the service is provided strictly for general informational purposes.
Clause 7.3 declines to warrant that outputs are correct, accurate, reliable, or free from bias or hallucinations. For a surface that can create payments and cancel mandates, that disclaimer is worth reading twice.
Clause 2.3 confirms the MCP is free today and reserves the right to charge later. Clause 2.4 reserves the right to suspend, modify, or withdraw any part of it without notice, and clause 10.1 allows termination for convenience.
Clause 7.1.5 prohibits use in connection with High-Risk Systems as defined by the EU AI Act, which matters if your agent touches lending or creditworthiness decisions.
None of this makes the MCP unusable. It does mean a revenue-critical collections pipeline built on it rests on a free service with a £50 liability cap and no notice period.
The maintenance question is not "which is less work today". It is "what breaks, and who is responsible for noticing".
GoCardless owns hosting, tool schemas, and endpoint normalisation. You do not write request builders or parse error envelopes, and when GoCardless ships a schema improvement you get it for free.
You own the session. That means detecting when a connection has hit its re-auth window, surfacing the sign-in prompt to the right merchant user, and pausing or queueing agent work while it is stale.
You also own schema drift. The tool surface is defined by GoCardless and changes on their schedule with no versioning contract, so enumerate tools at runtime rather than hardcoding a list you validated last quarter.
That is not a theoretical risk here. At the time of writing, the published GoCardless MCP developer page still describes account access as strictly read-only, while GoCardless's own product announcement and the live tool surface both include write tools.
You own everything: endpoint selection, pagination, the GoCardless-Version header, retry policy, idempotency key generation, and the full token lifecycle. That is more code.
What you get back is stability. Endpoints are versioned, the current version has been stable for years, and GoCardless publishes a backwards compatibility policy. Rate limit headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) let you back off deliberately, and the 29-second request timeout is documented rather than discovered. A nightly reconciliation job calling six endpoints is not affected by anything shipped to the MCP server.
Both lists below assume you are building something real, not a demo.
The auth divergence between the two paths is real, and it hides a problem sitting underneath both of them.
Both paths hand you a credential per merchant. The MCP gives you an OAuth session tied to a dashboard user with a fortnightly clock. The API gives you a permanent organisation-scoped token. In neither case does the path itself tell you where that credential lives.
Storage is yours: encrypted at rest, isolated per tenant, never in agent runtime or model context. Revocation is yours: when a customer churns or an employee leaves, you enumerate and invalidate every credential tied to that identity.
Lifecycle is the part teams underestimate. MCP sessions need proactive re-auth surfacing before they lapse, because a merchant who discovers the prompt only when a run fails has already lost the run.
Permanent API tokens need the opposite discipline: monitoring for the access_token_revoked reason on a 401, which is the only signal you get when a merchant disconnects your app. At 200 merchant organisations, that is 200 credentials on independent lifecycles. The path you pick changes the token type, not the infrastructure.
Scalekit's GoCardless MCP connector runs the per-user OAuth flow, stores the credential in a per-tenant token vault, and exposes connection status so your agent can surface a re-auth link instead of failing mid-task. Credentials never touch the agent runtime.
The same connected-account model covers the REST API path. If you need the endpoints the MCP does not expose, add your own connector pointed at the GoCardless API and call it through Tool Proxy. Same connections, same connected accounts, same authorisation flow, different upstream.
Three paths, depending on what your agent needs. All of them start with a connection named gocardlessmcp created in the Scalekit dashboard under AgentKit > Connections.
actions.langchain.get_tools returns the tools this identifier's connected account is authorised to call, already bound to that account, as native LangChain StructuredTool objects. No GoCardless token enters your agent code or the model context.
The connection_name string must match the connection name in your Scalekit dashboard character for character. A mismatch is the single most common reason for an empty tool list on the first run.
When you need explicit control over the two-phase handshake, call execute_tool yourself. The preview call returns the token; the confirm call must carry it, and must not fire until the merchant has actually replied.
The confirm is a separate turn. Extract preview_token from preview.data, present the preview, and only send the confirm after the merchant's next message; sending it immediately is rejected by the server.
Mastra has native MCP support through @mastra/mcp, so it discovers tools and Zod schemas straight from a Scalekit-generated URL. Mint that URL per user on your backend; a process-wide URL runs every request as one merchant.
For endpoints the MCP does not expose, define a custom connector for the GoCardless API and call it with actions.request. Scalekit injects the merchant's stored credential; you supply the version header and the idempotency key.
Handing an agent the whole connector is the default, and it is the wrong default for a payments integration.
A collections agent that reports on failed payments needs five read tools. Connect it to the raw GoCardless MCP and it also gets cancel_mandate, an irreversible tool whose own description notes it cascades to every subscription and pending payment on that mandate.
Least privilege at the tool level stops being a nicety when the blast radius is a merchant's recurring revenue.
Scalekit's rule of thumb is roughly 200 tokens per tool definition, which puts 24 tools near 4,800 tokens burned before the agent does any work. GoCardless's write tools run well above that average; create_payment_link alone carries 21 parameters with long constraint descriptions.
Virtual MCP servers address both. You declare which connections and which tools an agent role can see, get a static mcp_server_url, and mint a short-lived session token bound to one merchant before each run.
Create the server once per agent role, not once per merchant.
Before every run, confirm the merchant's connection is still active and mint a fresh token. This check is where a lapsed MCP session surfaces as a re-auth link rather than a mid-task failure.
One server definition serves every merchant. Each run resolves to that merchant's connected account, so a misbehaving run cannot reach another tenant's data.
For most connectors, tool-call logging is a debugging convenience. For a payments connector, it is the record you produce when someone asks who issued a £4,000 refund at 02:14.
Every Scalekit tool call returns an execution ID: execution_id in Python, executionId in Node. That ID ties the call to a connected account, an identifier, a tool name, and an input payload, which gives you the four facts an incident review actually needs: which merchant, which agent role, which tool, and what arguments.
Because execution runs through Scalekit rather than direct from your agent process, the audit trail for agent auth is produced by the layer holding the credential rather than reconstructed from application logs. Request and response visibility and OpenTelemetry export mean the trail lands in whatever observability stack you already run.
Two properties of the GoCardless MCP make attribution harder than usual. Payer identifiers are masked, so your logs will show CU000123 rather than a person, and reconciling that back to a customer means joining against your own records. And the preview-and-confirm handshake produces two calls per write, so a complete record has to pair them.
Logging both legs with their execution IDs gives you a defensible sequence: preview requested, preview shown, merchant replied, confirm sent, resource created. That is the difference between an audit answer and an apology. The same argument in general form is covered in Agent Tool Observability.
If your agent is a co-pilot with a merchant in the chat, build on the GoCardless MCP. The documentation tools have no API equivalent, masking is handled upstream, and the confirm gate is the control you want when a model is about to move money.
If your agent runs unattended or spans multiple merchant organisations, build on the REST API. The fourteen-day re-auth window and the absent Idempotency-Key are not friction to engineer around; they tell you what the surface was designed for.
One question settles it: does a human approve every write? If yes, the MCP is legitimate. If no, only the API survives production. Either way you store and revoke one credential per merchant, and that part deserves real infrastructure. For a deeper look at how secure token management for AI agents works at scale, that post covers the patterns and pitfalls in full.
Browse the Scalekit GoCardless MCP connector and the connector documentation, or start from an agent template if you want a working shape to adapt. Plans and limits are on the pricing page.
Building something on GoCardless and hitting one of the walls above? Join the Scalekit Slack community or talk to an engineer for help with your specific setup.
