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

Connect your AI Agents to PayPal in minutes

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

Start building for free

Read docs

PayPal

Learn more about Merge Agent Handler

Available tools

list_disputes

List PayPal disputes with optional filters for state and start time. Returns paginated results.

get_dispute

Get full details of a PayPal dispute by ID including transactions, messages, and evidence.

accept_dispute_claim

Accept a PayPal dispute claim and issue a refund to the buyer.

escalate_dispute

Escalate a PayPal dispute to a claim for PayPal to investigate and decide.

provide_dispute_evidence

Provide evidence for a PayPal dispute such as tracking info or proof of delivery.

acknowledge_return_item

Acknowledge receipt of a returned item in a PayPal dispute.

send_dispute_message

Send a message to the buyer or PayPal about a dispute.

make_dispute_offer

Make an offer to resolve a PayPal dispute with refund, return, or replacement.

create_invoice

Create a draft PayPal invoice. Requires detail with currency_code. Send separately.

list_invoices

List PayPal invoices with pagination. Returns invoice summaries.

get_invoice

Get details of a PayPal invoice by ID including items, amounts, and payment status.

update_invoice

Fully update a PayPal draft invoice. Cannot update sent invoices.

delete_invoice

Delete a PayPal draft invoice. Cannot delete sent or paid invoices.

send_invoice

Send a PayPal draft invoice to recipients via email. Changes status to SENT.

cancel_invoice

Cancel a sent PayPal invoice. Notifies recipient of cancellation.

record_invoice_payment

Record an external payment on a PayPal invoice (e.g., cash, check, bank transfer).

generate_invoice_number

Generate the next invoice number in PayPal's sequence.

create_order

Create a PayPal order with CAPTURE or AUTHORIZE intent. Include purchase_units with amount and items.

get_order

Get details of a PayPal order by ID including status, purchase units, and payment info.

update_order

Update a PayPal order's purchase_units using JSON Patch operations before capture.

capture_order

Capture payment for an approved PayPal order. Use after buyer approves the order.

authorize_order

Authorize payment for an approved PayPal order. Places a hold on buyer's funds.

confirm_order

Confirm a PayPal order with a specific payment source before capture or authorization.

get_authorized_payment

Get details of an authorized PayPal payment by authorization ID.

capture_authorized_payment

Capture funds from an authorized PayPal payment. Can capture full or partial amount.

void_authorized_payment

Void an authorized PayPal payment to release the hold on buyer's funds.

reauthorize_payment

Reauthorize a PayPal payment to extend the authorization period.

get_captured_payment

Get details of a captured PayPal payment by capture ID.

refund_captured_payment

Refund a captured PayPal payment. Can refund full or partial amount.

get_refund

Get details of a PayPal refund by refund ID.

create_payout

Create a PayPal payout batch to send money to multiple recipients via email, phone, or PayPal ID.

get_payout_batch

Get details of a PayPal payout batch by ID including status and all payout items.

get_payout_item

Get details of a specific PayPal payout item by ID including transaction status.

cancel_payout_item

Cancel an unclaimed PayPal payout item. Only works for items in UNCLAIMED status.

create_product

Create a catalog product in PayPal. Products are required before creating subscription plans.

list_products

List catalog products in PayPal with pagination. Use to find product IDs for plans.

get_product

Get details of a PayPal catalog product by ID.

update_product

Update a PayPal catalog product using JSON Patch operations.

create_plan

Create a billing plan for subscriptions. Requires a product_id. Use list_products first.

list_plans

List billing plans in PayPal with optional product_id filter. Returns paginated results.

get_plan

Get details of a PayPal billing plan by ID including billing cycles and pricing.

update_plan

Update a PayPal billing plan using JSON Patch operations.

activate_plan

Activate an inactive PayPal billing plan to make it available for subscriptions.

deactivate_plan

Deactivate a PayPal billing plan. Existing subscriptions continue but no new ones allowed.

update_plan_pricing

Update pricing for a PayPal billing plan. Changes apply to new billing cycles.

create_subscription

Create a PayPal subscription for recurring payments. Requires a plan_id. Use list_plans first.

get_subscription

Get details of a PayPal subscription by ID including billing info and status.

update_subscription

Update a PayPal subscription using JSON Patch operations.

activate_subscription

Activate a suspended PayPal subscription to resume billing.

suspend_subscription

Suspend a PayPal subscription to temporarily stop billing. Can be reactivated later.

cancel_subscription

Cancel a PayPal subscription permanently. Stops all future billing.

capture_subscription_payment

Capture outstanding balance on a PayPal subscription.

revise_subscription

Revise a PayPal subscription to change plan, quantity, or shipping. Requires buyer approval.

list_subscription_transactions

List transactions for a PayPal subscription within a date range.

validate_credential

Validate PayPal API credentials (client_id/client_secret). Used during credential setup to verify authentication is working correctly by fetching an access token from PayPal.

create_webhook

Create a PayPal webhook to receive event notifications at your URL. Max 10 per app.

list_webhooks

List all PayPal webhooks for your application.

get_webhook

Get details of a PayPal webhook by ID including URL and subscribed event types.

update_webhook

Update a PayPal webhook URL or event subscriptions using JSON Patch operations.

delete_webhook

Delete a PayPal webhook. Stops all event notifications to that URL.

list_webhook_event_types

List all available PayPal webhook event types you can subscribe to.

verify_webhook_signature

Verify a PayPal webhook signature to ensure the event is authentic.

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 PayPal MCP server

What is a PayPal MCP server?

It’s an MCP server that lets you access data and functionality from PayPal via tools. Your agents can use these tools to create invoices, list all recent disputes, confirm orders, and more.

PayPal offers an official MCP server here. You can also access a PayPal MCP server via a 3rd-party platform, like Merge Agent Handler.

What are some common tools for a PayPal MCP server?

Here are some popular options broken down by object types:

Invoices

<code class="blog_inline-code">list_invoices</code>
<code class="blog_inline-code">get_invoice</code>
<code class="blog_inline-code">update_invoice</code>
<code class="blog_inline-code">delete_invoice</code>

Orders

<code class="blog_inline-code">create_order</code>
<code class="blog_inline-code">confirm_order</code>
<code class="blog_inline-code">authorize_order</code>
<code class="blog_inline-code">update_order</code>

Payments

<code class="blog_inline-code">get_authorized_payment</code>
<code class="blog_inline-code">reuthorize_payment</code>
<code class="blog_inline-code">get_captured_payment</code>
<code class="blog_inline-code">get_refund</code>

Disputes

<code class="blog_inline-code">list_disputes</code>
<code class="blog_inline-code">get_dispute</code>
<code class="blog_inline-code">escalate_dispute</code>
<code class="blog_inline-code">provide_dispute_evidence</code>

How can I use a PayPal MCP server?

Here are some common use cases:

Automate refunds and disputes: Pull transaction details, gather supporting evidence, and submit dispute responses or issue refunds with consistent handling

Reconcile payments with internal records: Use transaction and payout data to match PayPal activity to invoices, orders, or subscription records and flag exceptions for review

Daily cash reporting: Use PayPal payouts, fees, and refund data to produce a daily snapshot of gross volume and net cash movement for finance

Fraud and risk triage: Use patterns in refunds, disputes, and transaction metadata to route suspicious activity into an investigation queue

Payment support: Use PayPal tools to answer questions like “where is my refund,” “did this payment go through,” and “what’s the status” with accurate, up-to-date details

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

Here are a few reasons:

Enterprise-grade authentication management: Merge Agent Handler provides built-in authentication flows that guide users through securely connecting third-party systems. This removes the need for developers to build and maintain authentication infrastructure themselves

Security gateway with data loss protection: All tool inputs and outputs are scanned through a security gateway that can block, redact, or modify sensitive data according to configured rules. This helps prevent agents from misusing sensitive information

Real-time observability and audit logs: Agent Handler tracks every tool call made by an AI agent, along with the underlying API request. Fully-searchable logs allow developers to audit behavior, debug issues, and monitor system interactions in real time

Built-in connector management: Using Connector Studio, developers can modify existing connectors or add new tools to customize integrations for their specific use cases

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

Yes, Merge Agent Handler includes a security gateway with data loss protection (DLP) that scans tool inputs and outputs for sensitive data. Developers can configure rules to block, redact, or mask specific data fields or types of information.

Prevent refund fraud and revenue leakage: Block refund-related tool calls that don't meet your policy, such as refunds over a dollar threshold, refunds outside an allowed time window, or refunds without an approved reason code

Stop sensitive payment data from ending up in tickets and notes: Block or redact card-like numbers and other sensitive strings before a PayPal write call succeeds

Enable support to help customers without exposing PII: Redact payer emails, phone numbers, and addresses in PayPal tool outputs so support can confirm status while limiting what they can see and repeat back to customers

Reduce the blast radius of account takeovers and prompt injection: Hard-block bulk “list all transactions” style calls or unusually large date ranges so an attacker can't use an agent to exfiltrate months of payment history

Enforce separation of duties between teams: Allow read-only PayPal tools for support workflows, but only allow refund and payout tools in a Finance tool pack so the agent can't take money-moving actions in the wrong context

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

You can follow these steps:

1. Sign up for Merge Agent Handler and grab your Agent Handler API key, since your MCP client will use it as a bearer token when calling the Agent Handler MCP endpoint.

2. Create a Tool Pack for your PayPal workflow, because Tool Packs define exactly which connectors and tools your agent is allowed to use.

3. Add the PayPal connector to that Tool Pack and select only the PayPal tools you want exposed for the workflow.

4. Create a Registered User (or decide on a service account pattern), since this identity is what scopes credentials and audit logs for tool calls.

5. Authenticate PayPal for that registered user using Merge Link (or Magic Link), so PayPal tools can run with the right credentials without you handling third-party tokens directly.

6. Copy the MCP entry URL that includes your Tool Pack ID and Registered User ID, and add it to your MCP client (Cursor, Claude Desktop, VSCode, Windsurf, etc.).

7. Configure your MCP client to send <code class="blog_inline-code">Authorization: Bearer <AGENT_HANDLER_API_KEY></code> on requests to that MCP URL, then start by running <code class="blog_inline-code">list_tools</code> and a simple PayPal read call to confirm everything is wired up.

8. Validate behavior in the Playground and Logs, and tighten the Tool Pack and rules once you confirm the happy path works (especially before enabling money-moving tools like refunds or payouts).

Explore other MCP servers built and managed by Merge

Front

Gamma

GitHub

GitLab

Gmail

Gong

Google BigQuery

Google Calendar

Google Docs

Google Drive

Google Maps

Google Meet

Google Sheets

Google Slides

Google Tasks

Grafana

Greenhouse

Guru

Hex

HiBob

HubSpot

Intercom

Jenkins

Jira

Ready to try it out?

Whether you're an engineer experimenting with agents or a product manager looking to add tools, you can get started for free now