Amp Configuration (~/.amp/servers.json)

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

Claude Configuration (~/.claude.json)

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

Token Generation

PayPal requires OAuth2 access tokens. Token validity:

Sandbox: 3-8 hours
Production: 8 hours

Generate Access Token

# Sandbox
curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "${PAYPAL_CLIENT_ID}:${PAYPAL_CLIENT_SECRET}" \
  -d "grant_type=client_credentials"

# Production
curl -X POST https://api-m.paypal.com/v1/oauth2/token \
  -H "Accept: application/json" \
  -H "Accept-Language: en_US" \
  -u "${PAYPAL_CLIENT_ID}:${PAYPAL_CLIENT_SECRET}" \
  -d "grant_type=client_credentials"

Token Refresh Script

#!/bin/bash
# paypal-token-refresh.sh
export PAYPAL_ACCESS_TOKEN=$(curl -s -X POST \
  "https://api-m.${PAYPAL_ENVIRONMENT:-sandbox}.paypal.com/v1/oauth2/token" \
  -H "Accept: application/json" \
  -u "${PAYPAL_CLIENT_ID}:${PAYPAL_CLIENT_SECRET}" \
  -d "grant_type=client_credentials" | jq -r '.access_token')
echo "Token refreshed: ${PAYPAL_ACCESS_TOKEN:0:20}..."

Available Tools

Invoices

Tool	Description
`create_invoice`	Create a new invoice
`list_invoices`	List all invoices
`get_invoice`	Get invoice details by ID
`send_invoice`	Send invoice to recipient
`send_invoice_reminder`	Send payment reminder
`cancel_sent_invoice`	Cancel a sent invoice
`generate_invoice_qr_code`	Generate QR code for invoice payment

Payments

Tool	Description
`create_order`	Create a payment order
`get_order`	Get order details
`pay_order`	Capture/execute payment
`create_refund`	Issue a refund
`get_refund`	Get refund status

Dispute Management

Tool	Description
`list_disputes`	List all disputes
`get_dispute`	Get dispute details
`accept_dispute_claim`	Accept a dispute claim

Shipment Tracking

Tool	Description
`create_shipment_tracking`	Add tracking info to transaction
`get_shipment_tracking`	Get tracking status

Catalog Management

Tool	Description
`create_product`	Create product in catalog
`list_products`	List all products
`show_product_details`	Get product details
`update_product`	Update product info

Subscription Management

Tool	Description
`create_subscription_plan`	Create billing plan
`update_plan`	Update plan details
`list_subscription_plans`	List all plans
`show_subscription_plan_details`	Get plan details
`create_subscription`	Create subscription for customer
`show_subscription_details`	Get subscription status
`update_subscription`	Modify subscription
`cancel_subscription`	Cancel active subscription

Reporting

Tool	Description
`list_transactions`	List transactions with filters

Key Use Cases

1. Create and Send Invoice

User: Create an invoice for $150 consulting fee to client@example.com

Agent Flow:
1. create_invoice(amount: 150, currency: "USD", recipient: "client@example.com", description: "Consulting services")
2. send_invoice(invoice_id: "<returned_id>")
3. generate_invoice_qr_code(invoice_id: "<returned_id>")

2. Process Order Payment

User: Create an order for $99.99 and capture payment

Agent Flow:
1. create_order(amount: 99.99, currency: "USD", intent: "CAPTURE")
2. get_order(order_id: "<returned_id>") -- verify status
3. pay_order(order_id: "<returned_id>") -- capture funds

3. List Recent Transactions

User: Show me transactions from the last 7 days

Agent Flow:
1. list_transactions(start_date: "2024-12-24", end_date: "2024-12-31")

4. Subscription Workflow

User: Create a monthly $29 subscription plan

Agent Flow:
1. create_product(name: "Premium Service", type: "SERVICE")
2. create_subscription_plan(product_id: "<id>", name: "Monthly Premium", billing_cycles: [{frequency: "MONTH", price: 29}])
3. create_subscription(plan_id: "<plan_id>", subscriber_email: "user@example.com")

APT → PYUSD → PayPal Integration Pattern

Bridge crypto (Aptos) to fiat (PayPal) via PYUSD stablecoin:

┌─────────────────────────────────────────────────────────────────┐
│                    APT → PYUSD → PAYPAL FLOW                     │
└─────────────────────────────────────────────────────────────────┘

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│   APT    │────▶│  DEX     │────▶│  PYUSD   │────▶│  PayPal  │
│  Wallet  │     │  Swap    │     │  Bridge  │     │  Payout  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
     │                │                │                │
     │ aptos_swap     │ liquidswap     │ pyusd_redeem   │ create_order
     │                │                │                │ pay_order

Triadic Flow (GF(3) Balanced)

;; +1 GENERATOR: Aptos swap APT→PYUSD
(aptos_swap {:from "APT" :to "PYUSD" :amount 100})

;; 0 COORDINATOR: Bridge PYUSD to PayPal (this skill)
(create_order {:amount 100 :currency "USD" :funding "PYUSD"})

;; -1 VALIDATOR: Verify settlement
(get_order {:order_id order-id})  ;; Confirm COMPLETED status

DuckDB Tracking

CREATE TABLE paypal_bridge_txns (
  txn_id VARCHAR PRIMARY KEY,
  aptos_txn_hash VARCHAR,
  pyusd_amount DECIMAL(18,6),
  usd_amount DECIMAL(10,2),
  paypal_order_id VARCHAR,
  status VARCHAR,  -- PENDING, BRIDGED, SETTLED, FAILED
  created_at TIMESTAMP,
  settled_at TIMESTAMP,
  gf3_trit INT CHECK (gf3_trit IN (-1, 0, 1))
);

Environment Variables

Variable	Required	Description
`PAYPAL_ACCESS_TOKEN`	Yes	OAuth2 access token
`PAYPAL_ENVIRONMENT`	Yes	`SANDBOX` or `PRODUCTION`
`PAYPAL_CLIENT_ID`	For refresh	App client ID
`PAYPAL_CLIENT_SECRET`	For refresh	App client secret

Error Handling

Common PayPal API errors:

AUTHENTICATION_FAILURE - Token expired, refresh required
INVALID_RESOURCE_ID - Invoice/order not found
PERMISSION_DENIED - Scope not authorized
RATE_LIMIT_REACHED - Too many requests, backoff

Triadic Skill Composition

PayPal-MCP as ERGODIC (0) coordinator in payment triads:

┌─────────────────────────────────────────────────────────────────┐
│  PAYMENT TRIAD                                                   │
├─────────────────────────────────────────────────────────────────┤
│  +1 GENERATOR   │  aptos-agent      │  Create crypto txn        │
│   0 COORDINATOR │  paypal-mcp       │  Bridge to fiat           │
│  -1 VALIDATOR   │  duckdb-ies       │  Verify settlement        │
├─────────────────────────────────────────────────────────────────┤
│  Σ trits = (+1) + (0) + (-1) = 0 ≡ 0 (mod 3) ✓                 │
└─────────────────────────────────────────────────────────────────┘

Amp Configuration (~/.amp/servers.json)

Claude Configuration (~/.claude.json)

Token Generation

Generate Access Token

Token Refresh Script

Available Tools

Invoices

Payments

Dispute Management

Shipment Tracking

Catalog Management

Subscription Management

Reporting

Key Use Cases

1. Create and Send Invoice

2. Process Order Payment

3. List Recent Transactions

4. Subscription Workflow

APT → PYUSD → PayPal Integration Pattern

Triadic Flow (GF(3) Balanced)

DuckDB Tracking

Environment Variables

Error Handling

Triadic Skill Composition

See Also

References

paypal-mcp

paypal-mcp Skill

GF(3) Assignment

MCP Server Setup