PayPal MCP Server: Cursor IDE Setup (2026)

How do you connect PayPal MCP to Cursor? Add a paypal entry to ~/.cursor/mcp.json that runs npx -y @paypal/mcp --tools=all locally with a PAYPAL_ACCESS_TOKEN and PAYPAL_ENVIRONMENT (SANDBOX or PRODUCTION) in the env block, or point Cursor at PayPal's hosted endpoint — https://mcp.sandbox.paypal.com for testing, https://mcp.paypal.com for production. Either path gives Cursor real tools for invoices, orders, refunds, disputes, and subscriptions against your actual PayPal account instead of hand-written REST calls against documentation examples.

This is PayPal's own official server (@paypal/mcp on npm, paypal/paypal-mcp-server on GitHub) — not a third-party wrapper. It's the natural pairing for anything already using the Stripe MCP server setup: most stores running both processors want the same "ask Cursor about a real transaction" workflow on both sides, not just Stripe's.

What PayPal MCP Gives You in Cursor

Once connected, you can ask Cursor things like:

Cursor calls PayPal's actual API through the MCP tools, gets back real invoice IDs, order statuses, and dispute records, then writes code (or takes the action directly, if you approve the write) against those real values instead of guessing at field names from PayPal's REST docs.

Prerequisites

Method 1: Local Server via npx (Recommended for Development)

This is the fastest path and matches PayPal's own quickstart.

Step 1: Generate an Access Token

PayPal's MCP server authenticates with a bearer access token, not a raw Client ID/Secret pair — you exchange your credentials for that token yourself, first. Get your Client ID and Secret from the Developer Dashboard, then request a token via OAuth2 client credentials:

curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Swap api-m.sandbox.paypal.com for api-m.paypal.com once you move to production credentials. The response is a JSON object with an access_token field and an expires_in value in seconds — PayPal's own docs show examples in the 15-minutes-to-~8.7-hours range depending on scope, so treat this token as short-lived, not a set-and-forget secret like a Stripe restricted key.

Step 2: Add the Server to mcp.json

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "@paypal/mcp", "--tools=all"],
      "env": {
        "PAYPAL_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN",
        "PAYPAL_ENVIRONMENT": "SANDBOX"
      }
    }
  }
}

Set PAYPAL_ENVIRONMENT to PRODUCTION once you've tested against sandbox and are ready to point at your live account. Never put a production token in a mcp.json that's committed to a shared repo — use Cursor's ${env:VAR} interpolation instead:

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "@paypal/mcp", "--tools=all"],
      "env": {
        "PAYPAL_ACCESS_TOKEN": "${env:PAYPAL_MCP_TOKEN}",
        "PAYPAL_ENVIRONMENT": "PRODUCTION"
      }
    }
  }
}

Step 3: Restart Cursor and Verify

Restart Cursor, check Settings → Tools & Integrations → MCP Tools for a green dot next to paypal, then test in chat:

List the 5 most recent orders on my sandbox PayPal account

A real (even if empty) list back means the token and environment are wired correctly. An auth error means the token expired or was copied wrong — see Troubleshooting below.

Method 2: Remote Hosted Server

PayPal also runs its own hosted MCP endpoints, so there's nothing to install locally:

Each supports two transports — append /sse for Server-Sent Events or /http for Streamable HTTP:

{
  "mcpServers": {
    "paypal": {
      "url": "https://mcp.sandbox.paypal.com/http",
      "headers": {
        "Authorization": "Bearer ${env:PAYPAL_MCP_TOKEN}"
      }
    }
  }
}

The remote path authenticates the same way as the local one — a bearer access token from the OAuth2 client-credentials exchange in Step 1 above — so the short-lived-token caveat applies here too. Use the remote path if you'd rather not run a local Node process, or if your team wants every developer hitting the same PayPal-managed infrastructure instead of a locally-spawned server per machine.

Available Tools

--tools=all enables the full catalog. The tools PayPal's server exposes, grouped by what they touch:

That's 30+ tools, more than most teams need loaded into every session. Instead of --tools=all, scope the --tools argument to just the categories you're actually working with (invoices and orders for a billing feature, subscriptions for recurring-plan work) — a narrower toolset means fewer tool-selection mistakes and less context spent describing tools you never call. PayPal's own docs cover the exact category syntax; check the npm package page for the current definitive list before assuming a category name from an older blog post still matches.

Notice what's absent: there's no create_refund-adjacent "void payment" or account-transfer tool, and nothing that manages PayPal's own OAuth apps or webhooks. This server is scoped to commerce objects — invoices, orders, disputes, subscriptions — not account administration.

Practical Workflows

Debugging a failed order:

Order ORDER_ID isn't showing as captured on our end. Look it up in PayPal
and tell me its current status and whether pay_order was ever called on it.

Building a subscription feature:

Create a subscription plan called "Team" at $99/month, then show me the
plan ID so I can wire it into our signup flow.

Investigating a dispute:

List all open disputes from the last 30 days and summarize what each one is about.

Reconciliation:

Pull the last 50 transactions and flag any that don't have a matching
invoice in our system.

PayPal MCP vs. Stripe MCP: Running Both

Stores that accept both processors end up needing both MCP servers side by side. A few differences matter when you're configuring them together in the same mcp.json:

If your app charges through both processors, name the mcpServers entries distinctly (paypal-sandbox / paypal-live, stripe-test / stripe-live) rather than relying on a single generic paypal or stripe key — see the Stripe MCP server guide for the same dual-environment pattern applied there.

When NOT to Use This

Don't wire --tools=all — with create_refund, cancel_subscription, and accept_dispute_claim all live — into an autonomous agent loop that acts without human approval on a production PayPal account. A refund or a canceled subscription is hard to walk back cleanly. Scope to read-heavy tool categories for anything that isn't a supervised, one-off task, and keep Cursor's "confirm before running" setting on for write tools.

Troubleshooting

"Invalid access token" or 401 errors
The most common cause isn't a typo — it's that the token expired. PayPal access tokens are short-lived (as little as 15 minutes, rarely more than about 9 hours). Re-run the client-credentials exchange from Step 1 and update PAYPAL_ACCESS_TOKEN (or the environment variable it points at).

Server connects but every call fails with a permissions-style error
Confirm PAYPAL_ENVIRONMENT matches the token you generated. A sandbox token against PRODUCTION (or the reverse) fails in ways that look like a permissions problem but are actually an environment mismatch.

Tools list looks incomplete
Check the --tools argument in your mcp.json — if it's scoped to a specific category instead of all, you'll only see tools from that category, by design.

Remote endpoint times out or refuses to connect
Confirm you're using the correct base URL for your environment (mcp.sandbox.paypal.com vs. mcp.paypal.com) and a supported transport suffix (/sse or /http). A bare base URL with no suffix isn't a documented entry point.

Works in sandbox, fails in production
Production requires a PayPal Business account, not just a Developer account. Confirm the account tied to your production Client ID/Secret is actually a Business account before assuming the MCP server itself is broken.

Frequently Asked Questions

Q: What is PayPal MCP Cursor setup?
A: It's connecting PayPal's official Model Context Protocol server — either the local @paypal/mcp npx package or PayPal's hosted sandbox/production endpoints — to Cursor's mcp.json, so Cursor's AI can query and act on real PayPal invoices, orders, refunds, disputes, and subscriptions instead of working from documentation examples alone.

Q: Do I need a PayPal Business account to use this?
A: Only for production. Sandbox testing works with a free PayPal Developer account and sandbox test accounts you create in the Developer Dashboard. Production access requires a real PayPal Business account tied to your live Client ID and Secret.

Q: How long does my PAYPAL_ACCESS_TOKEN last?
A: PayPal's OAuth2 client-credentials tokens are short-lived — commonly in the range of 15 minutes to roughly 9 hours depending on scope. There's no automatic refresh built into the static env value in mcp.json; you need to regenerate the token and update your config (or script the refresh) once it expires.

Q: Local npx server or remote hosted endpoint — which should I use?
A: The local npx @paypal/mcp path is the faster way to start and matches PayPal's own quickstart, running the process on your machine. The remote hosted endpoints (mcp.sandbox.paypal.com / mcp.paypal.com) skip the local Node process entirely and are a better fit for teams standardizing on PayPal-managed infrastructure rather than a locally spawned server per developer.

Q: Can this refund a customer or cancel a subscription on its own?
A: Yes, if you enable those tools — create_refund and cancel_subscription are both in the default --tools=all set. Because those are consequential write actions, keep Cursor's tool-call confirmation on and consider scoping --tools to read-only categories for anything running without a human approving each call.

Q: I run both Stripe and PayPal — can I connect both MCP servers in Cursor at once?
A: Yes. Add both as separate entries under mcpServers in the same mcp.json, and give each a distinct name per environment (e.g. paypal-sandbox, stripe-test) so you're never ambiguous in a prompt about which processor or environment you mean.

Q: What's the difference between the sandbox and production base URLs?
A: mcp.sandbox.paypal.com talks to PayPal's sandbox environment using sandbox credentials and test accounts — nothing here touches real money. mcp.paypal.com is the live endpoint against your real PayPal Business account. Match your access token's environment to the URL you're calling; mixing them produces authentication errors that look unrelated to the actual mismatch.

Q: Does the PayPal MCP server support webhooks?
A: Not directly — there's no create_webhook or webhook-management tool in the current catalog. The server's tools are scoped to invoices, orders, disputes, subscriptions, shipment tracking, catalog items, and transaction reporting. Webhook configuration still happens through the PayPal Developer Dashboard or the standard REST API outside of MCP.

Related Guides

Official docs cited