/setup

description: Configure PayPal plugin — verify credentials, test MCP server connection, and show active environment
argument-hint: [mode — e.g. "refresh", "status"]
allowed-tools: Read, Bash, mcp__paypal-sandbox__*

PayPal Setup

Walk the user through PayPal plugin configuration for Claude Code. Verify everything works before they use other commands.

Workflow

Step 1: Check MCP Connection

Two checks, sandbox-first:

1. **Is the sandbox MCP connected?** Count tools whose name matches `mcp__paypal-sandbox__*` in this session. If any are present, run one lightweight probe (`mcp__paypal-sandbox__list_invoices` with `page_size: 1`). Report the tool count from the session. 2. **Is the sandbox token in `~/.claude/settings.json`?** Read the file and check whether the `"env"` block has a non-empty `"PAYPAL_SANDBOX_ACCESS_TOKEN"`.

Report

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PayPal Plugin Setup
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  [✓] Sandbox MCP                — connected (31 tools)
  [✓] Sandbox token in settings  — set

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If the MCP isn't connected OR the probe returns an error (401, SSE header invalid, etc.), report `needs setup` and go to Step 2. If the MCP is connected but tool count looks low (less than 10), note it briefly and proceed to Step 2 to help the user upgrade.

  [!] Sandbox MCP                — needs setup
  [!] Sandbox token in settings  — not set

**If MCP tools aren't loaded at all** (no `mcp__paypal-sandbox__*` tools in the session and `/mcp` doesn't list `paypal-sandbox`): the plugin isn't installed correctly. Fix:

• Marketplace: `/plugin marketplace add paypal/AI-Toolkit` then `/plugin install paypal@paypal-ai-toolkit`
• Local: `claude --plugin-dir /path/to/AI-Toolkit`

Internal knowledge for the LLM (do not surface unless asked)

Two auth paths reach the same PayPal hosted gateway, and they produce different tool counts. Keep this in mind when interpreting results, but don't lead with it:

| Server | Auth path | Tools | | ---------------- | ------------------------------------- | ------------------------------------------------- | | `paypal-sandbox` | Bearer (env var from `settings.json`) | 31 | | `paypal-sandbox` | OAuth (browser flow via `/mcp`) | 4 (PayPal sandbox scope is intentionally limited) |

Rules for using this:

• Recommend the env-var route by default — it's the only way to get 31 tools in sandbox.
• If a sandbox user is seeing exactly 4 tools, they're on OAuth — gently suggest setting the token in `settings.json` to unlock the full toolkit. Do not lecture about scopes; just say "to get the full 31-tool surface, set `PAYPAL_SANDBOX_ACCESS_TOKEN` in `~/.claude/settings.json`."
• Don't bring up OAuth vs Bearer terminology unless the user asks "why am I only seeing 4 tools?" — until then it's noise.
• The `SSE error: Header has invalid value` failure mode means the env var is set but contains whitespace/newlines (usually from a multi-line `~/.zshrc` export). Fix: regenerate, put on a single line in `settings.json`.

Step 2: Diagnose why a set token still fails

Reach this step only when Step 1 reports the sandbox token IS set in `~/.claude/settings.json` but the MCP server still fails to connect (probe returns 401, SSE error, or no tools loaded).

Likely causes, in order of frequency:

1. **Token expired.** PayPal access tokens last up to 8 hours depending on scope. Most common. → Step 3 to regenerate. 2. **Token has stray whitespace or a newline.** Usually from a copy-paste that picked up the surrounding quote characters, or from a multi-line `~/.zshrc` export that was migrated to `settings.json` without flattening. JSON should reject this, but if it survived, the `Authorization` header will be rejected by Node's HTTP layer (`SSE error: Header has invalid value`). → Open `settings.json`, confirm the value is a single line with no whitespace, regenerate if unsure. 3. **Gateway rate-limited (`HTTP 429`).** You've been reconnecting too often during testing. Auth is fine — just wait 1–2 minutes. Do not regenerate. 4. **Network issue.** Behind a corporate VPN/proxy. Check connectivity to `mcp.sandbox.paypal.com`.

If none of the above resolve it, go to Step 3 and generate a fresh token from scratch.

**If the token was NOT set in Step 1:** skip Step 2 and go straight to Step 3.

Step 3: Credential Setup

Guide the user through generating a sandbox access token.

Sandbox Setup

Let's set up your PayPal sandbox credentials.

1. Go to: https://developer.paypal.com/dashboard/applications/sandbox
2. Create an app (or use the default "My Testing Application")
3. Copy your Client ID and Client Secret

Then generate an access token (the resulting value is one line):

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

Paste the returned A21AA… string into ~/.claude/settings.json under the
"env" block (recommended over ~/.zshrc — GUI-launched Claude Code doesn't
read shell profiles, and a multi-line export breaks the Authorization
header):

  {
    "env": {
      ... other keys ...,
      "PAYPAL_SANDBOX_ACCESS_TOKEN": "A21AA…"
    },
    ...
  }

Then FULLY QUIT Claude Code (close the app — not just /clear) and reopen.

Wait for the user to confirm they've set the token. Then re-verify by attempting an MCP tool call.

**If 401 / Unauthorized:** "Token was rejected. It may be malformed, expired, or copied with a stray newline. Regenerate with the curl command above — copy the value as a single line."

**If timeout / network error:** "Check your network connection. If you're behind a corporate proxy or VPN, you may need to allowlist `mcp.sandbox.paypal.com`."

Step 3.5: Project Environment Check