PayPal AI Toolkit

A plugin that integrates PayPal's APIs and MCP server into your AI coding workflow. Get AI-assisted help with PayPal payments, subscriptions, invoices, disputes, and more — in Claude Code, OpenAI Codex, Cursor, and other compatible agents.

• Best practices Skill — auto-injects PayPal API knowledge when you're working on payment integrations
• Commands — quick reference commands for common developer tasks (Claude Code and Cursor)
• Hooks — automatically checks PayPal best practices before writing integration code
• MCP Server integration — connects your agent to PayPal's sandbox MCP servers for direct API operations via natural language

• A PayPal Developer account at https://developer.paypal.com
• A PayPal sandbox access token
• Claude Code (claude --version), OpenAI Codex (codex --version), and/or Cursor

PayPal AI Toolkit is available on the official Anthropic marketplace, which Claude Code adds automatically. Install it with:

/plugin install paypal@claude-plugins-official

Then run /reload-plugins to activate it.

To work on the plugin itself, clone the repo and load it directly instead:

git clone https://github.com/paypal/AI-Toolkit.git

Then start Claude Code with the plugin loaded:

cd your-project/
claude --plugin-dir /path/to/AI-Toolkit

Add the PayPal marketplace, then install the plugin:

codex plugin marketplace add paypal/AI-Toolkit
codex plugin add paypal@paypal-ai-toolkit

git clone https://github.com/paypal/AI-Toolkit.git
codex plugin marketplace add /path/to/AI-Toolkit
codex plugin add paypal@paypal-ai-toolkit

Restart Codex after installing so skills and the sandbox MCP server load.

Add this repository as a marketplace, then install the plugin:

cursor-agent plugin marketplace add https://github.com/paypal/AI-Toolkit

Then open Customize (or type /plugin) and install paypal at user or project scope.

Once the plugin is listed on the Cursor marketplace, you can also install it from chat with /add-plugin paypal.

Load the checkout directly (no marketplace or admin setting required):

git clone https://github.com/paypal/AI-Toolkit.git
cursor-agent --plugin-dir /path/to/AI-Toolkit

You can also copy the repo into Cursor's local plugin folder. This requires Allow Local Plugin Imports (Dashboard → Settings → Security & Identity → Marketplace and Plugins), which is off by default on some teams. Symlinks that point outside this folder are skipped:

git clone https://github.com/paypal/AI-Toolkit.git ~/.cursor/plugins/local/paypal

cursor-agent plugin marketplace add only accepts a git URL (for example https://github.com/paypal/AI-Toolkit), not a local path.

Restart Cursor or run Developer: Reload Window, then confirm skills, commands, and paypal-sandbox in Customize.

1. Generate a sandbox access token:

   curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
     -u "YOUR_SANDBOX_CLIENT_ID:YOUR_SANDBOX_CLIENT_SECRET" \
     -d "grant_type=client_credentials" \
     | jq -r .access_token

   Get the client ID and secret from the PayPal Developer Dashboard.

2. Paste the single-line value into your agent's config.

   Claude Code — merge into the existing "env" block in ~/.claude/settings.json:

   "env": {
     "PAYPAL_SANDBOX_ACCESS_TOKEN": "A21AA…"
   }

   OpenAI Codex — merge into ~/.codex/config.toml:

   [shell_environment_policy.set]
   PAYPAL_SANDBOX_ACCESS_TOKEN = "A21AA…"

   Cursor — after installing the plugin, open Customize → Plugins → PayPal → Configure and paste the token. Cursor stores it and substitutes ${PAYPAL_SANDBOX_ACCESS_TOKEN} in .mcp.json. A GUI-launched Cursor does not inherit export from ~/.zshrc.

3. Fully quit and reopen the agent (close the app — not just /clear).

4. In Claude Code, run /paypal:setup to verify. In Codex or Cursor, ask the agent to list PayPal MCP tools or create a sandbox invoice.

Use the agent config or Cursor plugin Configure panel, not ~/.zshrc. GUI launches don't source ~/.zshrc, and a line-wrapped export embeds a newline in the token that breaks the HTTP header.

Tokens expire in up to 8 hours depending on scope — check the expires_in field in the response. Run /paypal:setup refresh when you hit a 401.

Slash commands are available in Claude Code and Cursor. Codex uses the same skills and MCP server through natural language.

/paypal:explain-error INSTRUMENT_DECLINED
/paypal:explain-error 422 UNPROCESSABLE_ENTITY
/paypal:sandbox subscriptions
/paypal:sandbox webhooks
/paypal:setup
/paypal:doctor webhooks not firing

The plugin connects to PayPal's sandbox MCP server, which exposes tools for:

• Orders & Payments — create orders, capture payments, process refunds
• Invoices — create, send, manage, and generate QR codes for invoices
• Subscriptions — manage billing plans and subscriptions
• Disputes — list and respond to buyer disputes
• Catalog — manage products and pricing
• Shipment — create and track shipments
• Reporting — list transactions, get merchant insights

The server uses SSE at the /sse path. paypal-sandbox activates once you set PAYPAL_SANDBOX_ACCESS_TOKEN in ~/.claude/settings.json (Claude Code), ~/.codex/config.toml (Codex), or Customize → Plugins → PayPal → Configure (Cursor).

The paypal-best-practices skill is automatically invoked when your agent detects you're working on PayPal integrations. It provides:

• Recommended APIs and deprecated APIs to avoid
• Authentication and credential best practices
• Orders, Subscriptions, and Invoices API flows
• Webhook verification and security guidance
• Error handling patterns
• Sandbox testing guidance

The paypal-routing skill routes PayPal-related questions to the right command or reference file and is not directly user-invocable.

A PreToolUse hook checks whether a file edit touches PayPal SDK, API, or checkout code. If it does, the agent is required to consult the paypal-best-practices skill and the correct SDK version reference (v5 or v6) before writing the code.

AI-Toolkit/
├── .agents/
│   └── plugins/
│       └── marketplace.json     # Codex marketplace catalog
├── .claude-plugin/
│   ├── marketplace.json     # Claude Code marketplace registry
│   └── plugin.json          # Claude Code plugin manifest
├── .codex-plugin/
│   └── plugin.json          # Codex plugin manifest
├── .cursor-plugin/
│   ├── marketplace.json     # Cursor marketplace catalog
│   └── plugin.json          # Cursor plugin manifest
├── .mcp.json                # PayPal sandbox MCP server (SSE)
├── skills/
│   ├── paypal-best-practices/
│   │   ├── SKILL.md         # Auto-injected best practices context
│   │   └── references/      # Topic-specific integration guides
│   └── paypal-routing/
│       └── SKILL.md         # Intent routing (non-user-invocable)
├── commands/
│   ├── doctor.md            # /paypal:doctor
│   ├── explain-error.md     # /paypal:explain-error
│   ├── sandbox.md           # /paypal:sandbox
│   ├── setup.md             # /paypal:setup
│   └── test-accounts.md     # /paypal:test-accounts
├── hooks/
│   └── hooks.json           # Pre-write best-practices check
├── LICENSE                  # Apache-2.0
├── CONTRIBUTING.md          # Contribution and commit guidelines
└── README.md

See CONTRIBUTING.md for how to report issues, develop locally, and submit pull requests.

Commit messages and PR titles should follow Conventional Commits, for example:

feat: allow provided config object to extend other configs

• PayPal Developer Docs
• PayPal REST API Reference
• PayPal MCP Server
• PayPal Agent Toolkit
• PayPal Developer Dashboard