Merge Unified's Stripe integration Merge Agent Handler's Stripe MCP server

Connect your AI Agents to Stripe in minutes

Merge lets you securely connect your agents to Stripe and thousands of tools instantly

Start building for free

Read docs

Stripe

Learn more about Merge Agent Handler

Available tools

retrieve_balance

Retrieve the current balance of your Stripe account showing available and pending amounts by currency. Shows funds available for payout and funds pending from recent transactions.

list_balance_transactions

List all balance transactions with pagination and filtering by date, currency, payout, or transaction type. Shows detailed history of all funds movement including charges, refunds, payouts, and fees.

retrieve_balance_transaction

Retrieve complete details of a specific balance transaction including fees, net amount, and source information

create_charge

Create a charge to process an immediate payment from a customer using a saved payment source. Payment methods/sources must already exist and be attached to the customer; use listcustomerpaymentmethods to discover valid pm... IDs before charging.

retrieve_charge

Retrieve complete details of a specific charge by ID including amount, status, receipt URL, and refund information

update_charge

Update charge metadata, description, receipt email, or shipping information after the charge has been created

capture_charge

Capture a previously authorized charge to complete the payment and transfer funds from customer account to your account

list_charges

List all charges with cursor-based pagination and filtering by customer, payment intent, or creation date

search_charges

Search charges using Stripe's query syntax to find charges by amount, customer, status, or metadata fields

create_coupon

Create a new coupon for discounts and promotions. Use 'amountoff' for fixed discounts or 'percentoff' for percentage discounts. These are mutually exclusive. Set 'duration' to control how long the discount applies. Related: list_coupons (browse), apply to subscriptions/invoices.

retrieve_coupon

Retrieve complete details of a specific coupon including usage statistics and validity. Use to check coupon status before applying to customers or subscriptions. Related: createcoupon (creation), updatecoupon (modifications).

update_coupon

Update coupon properties including name and metadata. Only name and metadata can be updated after creation. Discount amounts, percentages, and duration cannot be changed. Related: createcoupon (creation), retrievecoupon (current details).

delete_coupon

Delete a coupon permanently to prevent future use. Existing subscriptions and customers using this coupon are not affected. Cannot be undone. Related: createcoupon (creation), listcoupons (find coupons to delete).

list_coupons

List all coupons with pagination and optional filtering by creation date. Use for browsing available coupons or finding specific coupons by date. For applying coupons, use retrievecoupon first to verify validity. Related: createcoupon (creation), retrieve_coupon (details).

create_customer

Create a new Stripe customer with email, payment details, and custom metadata for subscription and payment management

retrieve_customer

Retrieve complete details of a specific Stripe customer by ID including balance, payment methods, and subscription status

update_customer

Update an existing Stripe customer's information including email, address, metadata, and default payment source

delete_customer

Permanently delete a Stripe customer and cancel all active subscriptions associated with the account

list_customers

List all Stripe customers with cursor-based pagination, filtering by email or creation date, up to 100 per page

search_customers

Search Stripe customers using query syntax to find customers by email, name, phone, or custom metadata fields

list_customer_balance_transactions

Retrieve all balance transactions for a Stripe customer showing account credits, debits, and balance changes over time

create_customer_balance_transaction

Create a balance transaction to add credit or debit to a customer's Stripe account for future invoice payments

retrieve_dispute

Retrieve complete details of a specific dispute including evidence, status, and charge information

update_dispute

Update dispute evidence and metadata to respond to a chargeback or inquiry

close_dispute

Close a dispute as lost, accepting the chargeback and preventing further evidence submission

list_disputes

List all disputes with pagination and optional filtering by charge, payment intent, or creation date

retrieve_event

Retrieve complete details of a specific webhook event including the triggering object and request information

list_events

List all webhook events with pagination and optional filtering by creation date, delivery status, or event type

create_invoice

Create a new invoice for a customer. Use 'subscription' parameter for subscription billing, or 'pendinginvoiceitemsbehavior' for custom invoices with line items. These parameters are mutually exclusive. Returns a draft invoice. Workflow: createinvoice → finalizeinvoice → payinvoice OR sendinvoice. If setting defaultpaymentmethod, use listcustomerpaymentmethods first to discover valid pm... IDs for the customer. Related tools: retrieveupcominginvoice (preview), listinvoices (history).

retrieve_invoice

Retrieve complete details of a specific invoice including status, line items, and payment information. Use after createinvoice to check status, or to get invoice details before payment. Related: payinvoice (payment), update_invoice (modifications).

update_invoice

Update invoice properties including description, metadata, payment settings, and due date. Only works on draft invoices. Use before finalizeinvoice to make final changes. If setting defaultpaymentmethod, use listcustomerpaymentmethods first to discover valid pm... IDs for the customer. Related: createinvoice (creation), finalize_invoice (lock changes).

pay_invoice

Pay an invoice using the customer's default payment method or specified payment method. Use 'forgive=True' to forgive the invoice without payment, or 'paidoutofband=True' to mark as paid externally. These options are mutually exclusive. Use after finalizeinvoice. If specifying paymentmethod, use listcustomerpaymentmethods first to discover valid pm... IDs for the customer. Related: createpaymentintent (complex payments), retrieveinvoice (check status).

finalize_invoice

Finalize a draft invoice to make it ready for payment and prevent further modifications. Required step before payinvoice or sendinvoice. Makes invoice immutable. Related: createinvoice (draft creation), payinvoice (payment), send_invoice (email to customer).

send_invoice

Send an invoice to the customer via email with a link to pay online. Alternative to payinvoice for customer self-service payment. Requires finalized invoice. Related: finalizeinvoice (prerequisite), createinvoice (creation), retrieveinvoice (check payment status).

void_invoice

Void an open invoice to mark it as uncollectible and prevent further collection attempts. Alternative to deleteinvoice for finalized invoices. Cannot be undone. Related: deleteinvoice (draft only), markinvoiceuncollectible (bad debt).

list_invoices

List all invoices with pagination and optional filtering by customer, subscription, status, or other criteria. Use for browsing invoice history or finding invoices by simple filters. For complex queries, use searchinvoices. Related: searchinvoices (advanced queries), retrieve_invoice (specific invoice).

search_invoices

Search invoices using powerful query syntax to find invoices by customer, amount, status, metadata, or other properties. Searchable fields: customer, status, amount, currency, created, metadata. Query examples: 'status:paid', 'amount>1000', 'customer:cus123', 'metadata["orderid"]:"12345"'. Related: list_invoices (simple filtering).

delete_invoice

Delete a draft invoice permanently to prevent it from being finalized or sent to customers. Only draft invoices can be deleted. Returns a deletion confirmation object, not a full invoice. For finalized invoices, use voidinvoice instead. Related: voidinvoice (finalized invoices), create_invoice (creation).

mark_invoice_uncollectible

Mark an invoice as uncollectible to indicate that collection attempts should cease. Use for bad debt accounting. Invoice remains in system for records. Alternative to voidinvoice for different accounting treatment. Related: voidinvoice (cancellation), list_invoices (find uncollectible invoices).

retrieve_upcoming_invoice

Retrieve a preview of the upcoming invoice for a customer or subscription before it is created. Useful for showing customers what they'll be charged. The returned invoice has no ID since it's not yet created. Use before createinvoice to preview charges. Related: createinvoice (actual creation), list_subscriptions (find subscriptions to preview).

create_payment_intent

Create a payment intent to track the complete payment lifecycle from creation through confirmation and settlement. Use for one-time payments. For recurring billing, use subscriptions instead. When setting paymentmethod, use listcustomerpaymentmethods first to discover valid pm_... IDs for the customer.

retrieve_payment_intent

Retrieve complete details of an existing payment intent including status, amount, payment method, and next required actions

update_payment_intent

Update payment intent properties including amount, currency, payment method, description, or metadata before confirmation. When changing paymentmethod, use listcustomerpaymentmethods first to discover valid pm_... IDs for the customer.

confirm_payment_intent

Confirm a payment intent to attempt payment using the attached payment method and advance through authentication if required. If providing paymentmethod, use listcustomerpaymentmethods first to discover valid pm_... IDs for the customer.

capture_payment_intent

Capture a payment intent that was created with manual capture method to finalize payment and transfer funds. Only works for payment intents with capturemethod='manual' that are in 'requirescapture' status.

cancel_payment_intent

Cancel a payment intent to prevent payment processing and release any authorized funds back to the customer immediately

list_payment_intents

List all payment intents with pagination and optional filtering by customer, status, or creation date

search_payment_intents

Search payment intents using powerful query syntax to find payments by amount, customer, status, metadata, or other properties

create_payment_method

Create a new payment method. For card type, only tokenized input is supported (pm/tok via cardtoken or card['token']); raw PAN/CVC is blocked by Stripe policy. Use attachpaymentmethod to associate the method with a customer. Use listcustomerpaymentmethods to discover saved customer methods.

retrieve_payment_method

Retrieve complete details of a specific payment method including card information and billing details

update_payment_method

Update payment method billing information, metadata, or card details for an existing payment method. Raw PAN/CVC fields are blocked by Stripe policy. Use listcustomerpayment_methods to discover valid customer payment method IDs.

list_payment_methods

List all payment methods for a specific customer with pagination and filtering by payment method type. Prefer listcustomerpayment_methods as the canonical customer payment method discovery flow.

attach_payment_method

Attach a payment method to a customer for use in future payments and recurring subscription billing. Required after creating a payment method. Use listcustomerpayment_methods to verify attached methods.

detach_payment_method

Detach a payment method from a customer to remove it from their available payment options

list_customer_payment_methods

List all payment methods attached to a specific customer with type filtering and pagination support. Use this as the primary tool to discover valid pm... IDs for paymentintent, invoice, subscription, and charge operations.

create_payout

Create a payout to transfer funds from your Stripe balance to your bank account or debit card

retrieve_payout

Retrieve complete details of a specific payout including status, amount, and destination information

update_payout

Update payout metadata for record keeping and tracking purposes

cancel_payout

Cancel a pending payout before it is processed to prevent funds from being transferred

reverse_payout

Reverse a completed payout to return funds back to your Stripe balance

list_payouts

List all payouts with pagination and optional filtering by arrival date, creation date, destination, or status

create_price

Create a new price for a product with specified currency, amount, and billing configuration

retrieve_price

Retrieve complete details of a specific price including billing configuration and product association

update_price

Update price properties including active status, metadata, and currency options

list_prices

List all prices with pagination and optional filtering by product, currency, type, or other criteria

search_prices

Search prices using powerful query syntax to find prices by product, currency, amount, metadata, or other properties

create_product

Create a new product in your catalog with name, description, pricing, and metadata

retrieve_product

Retrieve complete details of a specific product including pricing, images, and metadata

update_product

Update product properties including name, description, images, pricing, and metadata

delete_product

Delete a product from your catalog to prevent it from being used in new purchases

list_products

List all products with pagination and optional filtering by active status, type, or other criteria

search_products

Search products using powerful query syntax to find products by name, description, metadata, or other properties

create_refund

Create a refund for a charge or payment intent to return funds to the customer

retrieve_refund

Retrieve complete details of a specific refund including status, amount, and failure information

update_refund

Update refund metadata for record keeping and tracking purposes

list_refunds

List all refunds with pagination and optional filtering by charge, payment intent, or creation date

cancel_refund

Cancel a pending refund before it is processed to prevent funds from being returned to the customer

create_subscription_item

Create a new subscription item to add products or services to an existing subscription

retrieve_subscription_item

Retrieve complete details of a specific subscription item including price, quantity, and billing information

update_subscription_item

Update subscription item properties including price, quantity, billing thresholds, and metadata

delete_subscription_item

Delete a subscription item to remove it from the subscription and stop billing for that item

list_subscription_items

List all subscription items for a specific subscription with pagination support

create_subscription

Create a new subscription for a customer with specified items, billing cycle, and payment settings. Requires at least one item with price and quantity. Use with createinvoice to bill immediately or let it bill automatically per the billing cycle. When setting defaultpaymentmethod, use listcustomerpaymentmethods first to discover valid pm_... IDs for the customer.

retrieve_subscription

Retrieve complete details of a specific subscription including status, items, and billing information

update_subscription

Update subscription properties including items, payment method, billing settings, and metadata. When setting defaultpaymentmethod, use listcustomerpaymentmethods first to discover valid pm... IDs for the customer.

cancel_subscription

Cancel a subscription immediately or at the end of the current billing period. Use 'cancelatperiodend=True' to cancel at period end (customer keeps access until then), or 'cancelatperiodend=False' for immediate cancellation.

list_subscriptions

List all subscriptions with pagination and optional filtering by customer, status, or other criteria

search_subscriptions

Search subscriptions using powerful query syntax to find subscriptions by customer, status, metadata, or other properties

resume_subscription

Resume a paused subscription to restart billing and service delivery

validate_credential

Validate Stripe credentials. Verifies credentials during setup.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Stripe MCP server

How can I use the Stripe MCP server?

Here are just a few examples:

Automated closed-won workflow: When a sales opportunity is marked as "Closed Won" in a CRM, your agent can automatically create a Stripe customer record, set up a subscription based on the deal terms, and send the first invoice. Your agent can then notify the account owner in an app like Slack with payment details

Customer health monitoring: When a Stripe payment fails or a subscription is cancelled, your agent can automatically update the opportunity status in your CRM, create a high-priority task for the customer success team, and post an alert in the relevant Slack channel with customer context

Invoice reconciliation: When Stripe invoices are finalized, your agent can automatically create corresponding records in your ERP system (like QuickBooks or NetSuite), attach invoice PDFs from cloud storage, and update financial reporting dashboards

Subscription analytics: Your agent can query Stripe subscription data, cross-reference it with customer usage data from your product analytics tool, and generate reports in Google Sheets or Notion showing revenue trends, churn patterns, and expansion opportunities

Automated refund workflows: When a customer requests a refund through your support ticketing system (like Zendesk), your agent can verify the original charge in Stripe, process the refund, update the ticket status, and log the transaction details in your internal documentation system

What are popular tools for Stripe’s MCP server?

Here are just a few popular tools across data types:

Charges

<code class="blog_inline-code">create_charge</code>
<code class="blog_inline-code">retrieve_charge</code>
<code class="blog_inline-code">update_charge</code>
<code class="blog_inline-code">list_charges</code>

Customers

<code class="blog_inline-code">create_customer</code>
<code class="blog_inline-code">retrieve_customer</code>
<code class="blog_inline-code">update_customer</code>
<code class="blog_inline-code">list_customer_balance_transactions</code>

Invoices

<code class="blog_inline-code">finalize_invoice</code>
<code class="blog_inline-code">pay_invoice</code>
<code class="blog_inline-code">send_invoice</code>
<code class="blog_inline-code">void_invoice</code>

What makes Merge Agent Handler’s Stripe MCP server better than alternative Stripe MCP servers?

Merge Agent Handler’s Stripe MCP server also provides platform-level capabilities:

Enterprise-grade security and DLP: All tool inputs and outputs are scanned by a security gateway with configurable data-loss-prevention rules, allowing sensitive data to be blocked, redacted, or masked before reaching third-party systems

Comprehensive and customizable tools: Merge’s pre-built Stripe connector comes with nearly 100 tools. You can use them as is or modify them, whether it’s editing their names, descriptions, or schema

Authentication and credential management: Merge handles the full authentication lifecycle for connectors, including guided user authorization flows and credential storage, so agents can securely call tools without custom auth logic

Tool Pack and access control management: Developers can bundle connectors and tools into Tool Packs and control which tools an agent can access, and whether authentication is shared or per-user

Real-time observability and audit trails: Every tool call is logged with a fully-searchable activity log, enabling auditing, debugging, and monitoring of agent behavior across Stripe and other tools

Can I set security rules for Stripe tool calls in Merge Agent Handler?

Yes, you can set a wide range of security rules for Stripe tool calls in Merge Agent Handler. Here are just a few examples:

Block bank account and routing numbers before they're sent to tools like <code class="blog_inline-code">create_customer</code> or <code class="blog_inline-code">create_payout</code>‍

Block Social Security Numbers (SSNs) from being included in customer metadata fields‍

Redact customer email addresses from Stripe responses before they reach your agent (e.g., when calling <code class="blog_inline-code">list_customers</code> or <code class="blog_inline-code">search_customers</code>)‍

Log all refund operations to track when agents call <code class="blog_inline-code">create_refund</code> or <code class="blog_inline-code">cancel_refund</code>‍

Log high-value payment intents (e.g., any <code class="blog_inline-code">create_payment_intent</code> call above a certain amount threshold)‍

Log subscription cancellations to monitor when agents invoke <code class="blog_inline-code">cancel_subscription</code>

How can I start using Merge Agent Handler’s Stripe MCP server?

Here's how to get started with Merge Agent Handler's Stripe MCP server:

1. Sign up for an account. Visit this page and register for a free Agent Handler account to access the dashboard.‍

2. Configure a Tool Pack. Tool Packs determine which connectors and capabilities your agent can tap into. Head to the Tool Packs section and select "Create Tool Pack." Add Stripe as one of your connectors, then choose your authentication approach (either Individual, where each user links their own Stripe account, or Shared for one centralized Stripe credential for all users).

3. Define a Registered User. Navigate to Registered Users and create an entry. This represents the identity—whether human or system—that’ll execute actions through your agent. When Stripe authentication is required, Agent Handler will automatically walk users through a guided connection flow, eliminating the need to build OAuth flows from scratch.

4. Test in Sandbox mode. Before deploying to production, verify that everything functions correctly. Open your Tool Pack's Sandbox environment and experiment with Stripe operations like retrieving customers, creating payment intents, or listing invoices.

5. Connect your agent application. Integrate your agent with Agent Handler using one of these methods:

Model Context Protocol: Copy the MCP configuration snippet from your Tool Pack settings and paste it into your agent's MCP client configuration. This instantly grants your agent access to all Stripe tools through the protocol‍
REST API: Alternatively, call Agent Handler's REST endpoints directly if your agent doesn't support MCP natively