PayPal Sandbox MCP Server

Servidor MCP remoto (Streamable HTTP) que expone dos tools de pago contra PayPal Sandbox, pensado exclusivamente para una demo de Salesforce Agentforce. Sin autenticación en el endpoint /mcp — solo apto para esta demo, nunca para producción.

1. Requisitos

• Node.js >= 20

• Una app de PayPal Developer (Sandbox) con Client ID y Client Secret

Related MCP server: PayPal MCP Server

2. Instalación

cd paypal-mcp-server
npm install

3. Variables de entorno

Copia .env.example a .env y rellena tus credenciales de Sandbox:

cp .env.example .env

El servidor nunca registra Client Secret, tokens de acceso ni cabeceras Authorization (ver src/logger.ts).

4. Arrancar localmente

npm run dev

o compilado:

npm run build
npm start

5. Probar GET /health

curl http://localhost:3000/health

Respuesta esperada:

{ "status": "UP", "environment": "sandbox", "mcpEndpoint": "/mcp" }

6. Probarlo con MCP Inspector

npx @modelcontextprotocol/inspector

En la UI del Inspector, elige transporte Streamable HTTP y apunta a http://localhost:3000/mcp. Deberías poder listar las tools create_paypal_payment y finalize_paypal_payment y ejecutarlas.

7. Despliegue

Cualquier hosting Node 20 sirve (Render, Railway, Fly.io, etc.). Con el Dockerfile incluido (multi-stage, usuario no root):

docker build -t paypal-mcp-server .
docker run -p 3000:3000 --env-file .env paypal-mcp-server

Este proyecto vive en el repo público Horizon-CX/PayPal-Sandbox-MCP-Server — puedes conectarlo directamente desde Render/Railway como origen de despliegue continuo.

8. Variables de entorno en el hosting

Configura en el panel del proveedor (Render/Railway/Fly.io):

• PAYPAL_CLIENT_ID

• PAYPAL_CLIENT_SECRET

• PAYPAL_ENVIRONMENT=sandbox

• PUBLIC_BASE_URL → la URL pública final asignada por el hosting (por ejemplo https://paypal-mcp-demo.onrender.com)

• PORT → normalmente la inyecta el propio hosting; déjala solo si el proveedor lo requiere explícito

9. Registrar el servidor en Salesforce

En Setup → MCP Servers → New:

⚠️ "No Authentication" solo es aceptable para esta demo con PayPal Sandbox. No debe utilizarse así en producción.

10. Tools a seleccionar

• create_paypal_payment

• finalize_paypal_payment

11. Ejemplos de input/output

create_paypal_payment

Input:

{
  "salesforceOrderId": "801xx0000000001",
  "orderNumber": "ORD-00001",
  "amount": "49.99",
  "currency": "EUR",
  "description": "Pedido demo Agentforce"
}

Output (structuredContent):

{
  "success": true,
  "salesforceOrderId": "801xx0000000001",
  "orderNumber": "ORD-00001",
  "paypalOrderId": "5O190127TN364715T",
  "approvalUrl": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
  "status": "CREATED",
  "paid": false,
  "amount": "49.99",
  "currency": "EUR"
}

finalize_paypal_payment

Input:

{
  "salesforceOrderId": "801xx0000000001",
  "paypalOrderId": "5O190127TN364715T"
}

Output cuando el comprador ya aprobó y se captura correctamente:

{
  "success": true,
  "salesforceOrderId": "801xx0000000001",
  "paypalOrderId": "5O190127TN364715T",
  "paypalStatus": "COMPLETED",
  "paymentStatus": "PAID",
  "paid": true,
  "captureId": "3C679366NW308354M",
  "amount": "49.99",
  "currency": "EUR"
}

Output cuando el comprador aún no ha aprobado:

{
  "success": true,
  "salesforceOrderId": "801xx0000000001",
  "paypalOrderId": "5O190127TN364715T",
  "paypalStatus": "CREATED",
  "paymentStatus": "PENDING_CUSTOMER_APPROVAL",
  "paid": false,
  "amount": "49.99",
  "currency": "EUR"
}

12. Advertencia

No Authentication solo es aceptable para esta demo con PayPal Sandbox. No debe utilizarse así en producción. Cualquier despliegue real de este patrón necesita autenticación en el endpoint /mcp (OAuth, API key, mTLS, etc.).

13. Crear un comprador PayPal Sandbox y aprobar el enlace

1. Entra en developer.paypal.com → Sandbox → Accounts.

2. Usa la cuenta personal (buyer) de sandbox que PayPal crea por defecto, o crea una nueva de tipo Personal.

3. Copia su email y contraseña de sandbox (botón "..." → View/edit account → Profile).

4. Abre el approvalUrl devuelto por create_paypal_payment en un navegador.

5. Inicia sesión con las credenciales del comprador sandbox del paso 3.

6. Aprueba el pago ficticio.

7. Verás la página /paypal/return de este servidor confirmando la aprobación.

8. Vuelve al chat de Agentforce y confirma que has pagado — esto debe disparar finalize_paypal_payment.

Scripts

Arquitectura

src/
  index.ts                    Bootstrap: config, servidor HTTP, graceful shutdown
  config.ts                   Validación de variables de entorno (Zod)
  logger.ts                   Logger pino con redacción de secretos
  paypal/
    paypalClient.ts           Cliente PayPal: OAuth2 con cache de token, createOrder/getOrder/captureOrder
    paypalTypes.ts            Tipos de las respuestas de PayPal
    paypalErrors.ts           Errores de dominio (nunca exponen credenciales/tokens)
  mcp/
    createServer.ts           Registro de las dos tools MCP
    tools/
      createPayPalPayment.ts
      finalizePayPalPayment.ts
  http/
    app.ts                    Express: /health, /paypal/return, /paypal/cancel, /mcp (POST/GET/DELETE)
    errorHandler.ts           Middleware de errores centralizado
tests/
  paypalClient.test.ts
  createPayPalPayment.test.ts
  finalizePayPalPayment.test.ts