PayPal MCP server
Use PayPal's hosted MCP server (sandbox and live) for invoices, orders, products, transactions, disputes and refunds.
PaymentsGuided#mcp#payments#invoicing#ai-agents#sandbox
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
PayPal's MCP server lets an AI assistant run everyday PayPal merchant tasks in plain language: create and send invoices, look up orders and transactions, manage catalog products and subscription plans, handle disputes, issue refunds and pull sales insights. PayPal hosts it remotely in two environments, so you can try everything in the sandbox before touching live money:
| Environment | Endpoint (Streamable HTTP) |
|---|---|
| Sandbox | https://mcp.sandbox.paypal.com/mcp |
| Production | https://mcp.paypal.com/mcp |
PayPal's quickstart also lists /sse endpoints for the older SSE transport and an /http path; on 2026-11-18 /mcp and /sse answered with an OAuth 401 while /http returned 404, so this collection uses /mcp. The tool catalog is the same as the open-source PayPal agent toolkit used by the local @paypal/mcp server.
Credentials (two options)
A. Access token from your REST app (used by this collection).
- Log in to the PayPal Developer Dashboard, open Apps & Credentials, stay on Sandbox, and create (or open) a REST app.
- Copy its Client ID and Secret into
clientIdandclientSecret. - Run Get a sandbox access token in folder 1. It calls PayPal's OAuth token endpoint with the client credentials grant and its test script saves the result into
accessToken. The MCP requests send it asAuthorization: Bearer {{accessToken}}. Tokens expire (seeexpires_in); run the request again when calls start failing with 401.
B. OAuth sign-in. Without a token the server returns 401 invalid_token with WWW-Authenticate: Bearer realm="OAuth", resource_metadata=".../.well-known/oauth-protected-resource/mcp". The metadata names the MCP host itself as the authorization server, with /authorize, /token, dynamic /register, PKCE S256 and refresh tokens. Clients such as Claude or Cursor (via mcp-remote) send you to the PayPal login page to consent. Folder 1 shows the discovery requests.
Add it to your AI client
- Claude Code:
claude mcp add --transport http paypal https://mcp.sandbox.paypal.com/mcp, then/mcpto log in with PayPal. - Claude Desktop (as in PayPal's guide):
{"mcpServers": {"paypal-mcp-server": {"command": "npx", "args": ["mcp-remote", "https://mcp.sandbox.paypal.com/sse"]}}}; add"--header", "Authorization: Bearer <access token>"to the args to use a token instead of the login page. - Cursor (
~/.cursor/mcp.json):{"mcpServers": {"paypal": {"url": "https://mcp.sandbox.paypal.com/mcp"}}}. - VS Code (
.vscode/mcp.json):{"servers": {"paypal": {"type": "http", "url": "https://mcp.sandbox.paypal.com/mcp"}}}.
If a login loop happens with mcp-remote, PayPal suggests deleting ~/.mcp-auth.
Run order and variables
Fill clientId and clientSecret (sandbox), run folder 1 to get accessToken, then folder 2 (invoices: create, copy the id into invoiceId, send), folder 3 (orders: create, copy the id into orderId), folder 4 (catalog), folder 5 (transactions, disputes, insights) and folder 6 (refunds; needs a captureId from a captured payment). Switch mcpUrl and apiBase to production only when you mean it.
Safety
send_invoice emails a real customer in production, pay_order captures money, create_refund returns money and accept_dispute_claim gives up a dispute. Use sandbox accounts and placeholder customers (John Doe, john@example.com), keep your client's tool approval on, and never let an agent refund or accept claims without a person checking. Rate limits follow PayPal's REST API (docs).
Common errors
| Response | Meaning | Fix |
|---|---|---|
HTTP 401 invalid_token | Missing or expired token | Re-run Get a sandbox access token |
| HTTP 401 from the token call | Wrong client id/secret or wrong environment | Use sandbox credentials with the sandbox host |
HTTP 404 on /http | Old path from the quickstart | Use /mcp |
| Tool error "Invalid PayPal Invoice ID" | Id has the wrong format | Copy ids from earlier results |
UNPROCESSABLE_ENTITY | Business rule failed (already sent, already refunded) | Read the tool's error detail |
Docs: MCP server quickstart, agent toolkit, REST authentication.
Endpoints 19
1. Start here: auth
- POSTGet a sandbox access token
{{apiBase}}/v1/oauth2/tokenExchanges your REST app's client id and secret for an access token with the client_credentials grant (HTTP Basic auth, form body). The test script stores… - POSTCall /mcp without a token (expect 401)
{{mcpUrl}}Sends an MCP initialize request without Authorization. The server answers 401 invalid_token with a WWW-Authenticate header pointing at its OAuth… - GETProtected resource metadata
{{mcpHost}}/.well-known/oauth-protected-resource/mcpReads the OAuth protected-resource document for the sandbox /mcp endpoint, which names the MCP host as its own authorization server and accepts tokens in the… - GETAuthorization server metadata
{{mcpHost}}/.well-known/oauth-authorization-serverReads the OAuth server metadata used for the PayPal login flow: authorize, token, dynamic registration and revocation endpoints, PKCE S256 and the…
2. Invoices
- MCPCreate a draft invoice
{{mcpUrl}}Calls create_invoice with flat top-level fields (currency_code, invoice_date, note, invoicer_business_name) plus primary_recipients (billing_info with name… - MCPList invoices
{{mcpUrl}}Calls list_invoices with optional page (from 1), page_size (up to 100) and total_required. Returns invoices with id, status (DRAFT, SENT, PAID, CANCELLED) and… - MCPGet an invoice
{{mcpUrl}}Calls get_invoice with invoice_id and returns the full invoice: status, recipients, items, totals, due amount and payment history. Use it to check whether a… - MCPSend an invoice
{{mcpUrl}}Calls send_invoice with invoice_id; note, send_to_recipient and additional_recipients are optional. In production this emails the customer a payment link, so…
3. Orders
- MCPCreate an order
{{mcpUrl}}Calls create_order with currencyCode (USD only in this tool) and items, each with name, quantity, itemCost, taxPercent and itemTotal; discount, shippingCost,… - MCPGet an order
{{mcpUrl}}Calls get_order with id (the order id from create_order) and returns status (CREATED, APPROVED, COMPLETED), purchase units and, once captured, the capture id… - MCPCapture an approved order
{{mcpUrl}}Calls pay_order with id to capture payment for an order the buyer has approved. This moves money in production. The result includes the capture id; copy it…
4. Catalog
- MCPCreate a product
{{mcpUrl}}Calls create_product with name and type (PHYSICAL, DIGITAL or SERVICE); description, category, image_url and home_url are optional. Products are the base for… - MCPList products
{{mcpUrl}}Calls list_products with optional page, page_size (up to 20 here) and total_required. Returns product ids and names to use with show_product_details or…
5. Reporting and disputes
- MCPList transactions
{{mcpUrl}}Calls list_transactions. start_date and end_date are ISO 8601 with seconds (defaults: the last 31 days); transaction_status S, P, V or D filters;… - MCPList disputes
{{mcpUrl}}Calls list_disputes with optional dispute_state (REQUIRED_ACTION, UNDER_PAYPAL_REVIEW, RESOLVED and others), disputed_transaction_id, page and page_size (max… - MCPGet a dispute
{{mcpUrl}}Calls get_dispute with dispute_id (from list_disputes) and returns the full case: reason, messages, evidence requested and deadlines. Read it before deciding… - MCPSales insights
{{mcpUrl}}Calls get_merchant_insights with start_date, end_date, insight_type (ORDERS or SALES) and time_interval (DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY). Returns…
6. Refunds (money movement)
- MCPRefund a capture
{{mcpUrl}}Calls create_refund with capture_id (from pay_order or the transaction list). Leave out amount for a full refund or pass amount with currency_code and value… - MCPGet a refund
{{mcpUrl}}Calls get_refund with refund_id and returns its status (PENDING, COMPLETED, FAILED, CANCELLED), amount and timestamps, so you can confirm the buyer was paid…
API details
- Base URL
https://mcp.sandbox.paypal.com/mcphttps://mcp.paypal.com/mcp- Authentication
- A bearer token in the Authorization header
OAuth 2.0 (authorization code flow) - Operations
- 19 operations on 19 pathsPOST 17GET 2
- Main resources
- 1. Start here: auth 42. Invoices 43. Orders 34. Catalog 25. Reporting and disputes 46. Refunds (money movement) 2
- Description format
- Swastik Codes guided collection, API version
checked against the docs on 2026-11-18 - Links
- Documentation
How to test the PayPal MCP server in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the PayPal MCP server collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get a sandbox access token” (POST {{apiBase}}/v1/oauth2/token), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the PayPal MCP server?
Use PayPal's hosted MCP server (sandbox and live) for invoices, orders, products, transactions, disputes and refunds. It is listed under Payments and has 19 endpoints.
Who publishes the PayPal MCP server?
It is listed from PayPal's public API description (an OpenAPI document), not published by PayPal on Swastik Codes. Anyone who controls paypal.com can claim the profile by adding a DNS TXT record.
What is the base URL of the PayPal MCP server?
Its description lists 2 base URLs: https://mcp.sandbox.paypal.com/mcp, https://mcp.paypal.com/mcp. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the PayPal MCP server?
It accepts 2 methods: A bearer token in the Authorization header; OAuth 2.0 (authorization code flow).
How many endpoints does the PayPal MCP server have?
19 operations on 19 paths (17 POST, 2 GET). The largest groups are 1. Start here: auth, 2. Invoices, 3. Orders, 4. Catalog.
Is forking the PayPal MCP server free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.