# Vexorpay MCP

Servidor MCP remoto de Vexorpay para conectar tu cuenta desde Claude Code, Cursor, VS Code y otros clientes MCP, con OAuth.

> [!WARNING]
> El SDK `vexor` de npm (Stripe, MercadoPago, PayPal, Square, Talo) está **deprecado**: ya no se mantiene y no debe usarse. Vexorpay es hoy una **API REST sobre Stripe, siempre en USD, sin SDK oficial**. Migración: <https://developers.vexorpay.com/docs/migracion-desde-el-sdk>

Fuente: <https://developers.vexorpay.com/docs/mcp>

El servidor MCP de Vexorpay expone las operaciones del API v1 como **herramientas MCP** (Model Context Protocol). Lo podés conectar a Claude Code, Cursor, VS Code o cualquier cliente MCP para crear links de pago, consultar cobros, responder disputas y más con lenguaje natural.

La conexión usa **OAuth**: autorizás el acceso desde el navegador (login + consentimiento) y el cliente MCP obtiene un token de acceso para llamar a las herramientas.

## Conectar

Elegí tu cliente y seguí los pasos. En todos los casos la conexión es por **OAuth**:
la primera vez que usás el servidor se abre el navegador para que inicies sesión,
autorices la app, elijas el **modo** (sandbox o producción) y los **permisos**
(scopes) que le otorgás.

### opencode

Agregá el servidor a tu `opencode.json`:

**opencode.json**

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vexorpay": {
      "type": "remote",
      "url": "https://mcp.vexorpay.com",
      "enabled": true,
      "oauth": {}
    }
  }
}
```

Después autenticá con OAuth desde la terminal:

**Terminal**

```bash
opencode mcp auth vexorpay
```

### Cursor

Editá `~/.cursor/mcp.json` (o `.cursor/mcp.json` en tu proyecto):

**mcp.json**

```json
{
  "mcpServers": {
    "vexorpay": {
      "url": "https://mcp.vexorpay.com"
    }
  }
}
```

Cursor abre el navegador para iniciar sesión y autorizar la primera vez que usás el servidor.

### Claude Code

Agregá el servidor con la CLI de Claude Code:

**Terminal**

```bash
claude mcp add --transport http vexorpay https://mcp.vexorpay.com
```

Iniciá Claude Code y corré `/mcp` para autenticar con OAuth.

### Claude Desktop

Abrí **Ajustes → Conectores → Agregar conector personalizado** y usá esta URL:

```text
https://mcp.vexorpay.com
```

Iniciás sesión y autorizás el acceso en el navegador.

### Codex

Agregá el servidor con la CLI de Codex:

**Terminal**

```bash
codex mcp add vexorpay --url https://mcp.vexorpay.com
```

Autenticá con OAuth cuando el cliente lo pida.

### ChatGPT

Abrí **Ajustes → Conectores → Agregar conector** (modo desarrollador) y usá esta URL:

```text
https://mcp.vexorpay.com
```

Autorizás el acceso con OAuth en el navegador.

### VS Code

Agregá el servidor a `.vscode/mcp.json` de tu workspace:

**mcp.json**

```json
{
  "servers": {
    "vexorpay": {
      "type": "http",
      "url": "https://mcp.vexorpay.com"
    }
  }
}
```

VS Code te pide autorizar con OAuth al iniciar el servidor.

### Other

Cualquier cliente MCP compatible con **Streamable HTTP** y OAuth se conecta a:

```text
https://mcp.vexorpay.com
```

Si tu cliente usa la configuración clásica de `mcpServers`:

**mcp.json**

```json
{
  "mcpServers": {
    "vexorpay": {
      "type": "http",
      "url": "https://mcp.vexorpay.com"
    }
  }
}
```

¿Usás un cliente que no está en la lista? Conectalo a
`https://mcp.vexorpay.com` (Streamable HTTP + OAuth).

## Entornos

| Entorno | URL del servidor MCP |
| --- | --- |
| **Producción** | `https://mcp.vexorpay.com` |
| **Sandbox** | `https://www.sandbox.vexorpay.com/api/mcp` |

El modo **sandbox** opera en modo de prueba (Stripe test) y es el ideal para desarrollar; el modo **producción** opera con dinero real. La conexión queda fijada al modo elegido al autorizar: no se puede alternar por llamada. Para cambiar de modo, reconectá la app con el modo que quieras.

## Herramientas

Hay 20 herramientas: todas las operaciones del API v1.

### Lectura (scope `read`)

| Herramienta | API v1 |
| --- | --- |
| `get_balance` | `GET /balance` |
| `list_payment_links` | `GET /payment-links` |
| `get_payment_link` | `GET /payment-links/{id}` |
| `list_charges` | `GET /charges` |
| `get_charge` | `GET /charges/{id}` |
| `list_subscriptions` | `GET /subscriptions` |
| `get_subscription` | `GET /subscriptions/{id}` |
| `list_disputes` | `GET /disputes` |
| `get_dispute` | `GET /disputes/{id}` |
| `list_events` | `GET /events` |
| `list_payouts` | `GET /payouts` |
| `list_acreditaciones` | `GET /acreditaciones` |

### Escritura

| Herramienta | API v1 | Scope |
| --- | --- | --- |
| `create_payment_link` | `POST /payment-links` | `links:write` |
| `update_payment_link` | `PATCH /payment-links/{id}` | `links:write` |
| `delete_payment_link` | `DELETE /payment-links/{id}` | `links:write` |
| `create_checkout` | `POST /payment-links/{id}/checkout` | `charges:write` |
| `update_subscription_seats` | `PATCH /subscriptions/{id}` | `subscriptions:write` |
| `cancel_subscription` | `POST /subscriptions/{id}/cancel` | `subscriptions:write` |
| `open_subscription_portal` | `POST /subscriptions/{id}/portal` | `subscriptions:write` |
| `respond_dispute` | `POST /disputes/{id}/response` | `disputes:write` |

Las herramientas destructivas (`delete_payment_link`, `cancel_subscription`, `respond_dispute`) requieren confirmación explícita en el cliente antes de ejecutarse.

## Scopes

Al autorizar la app elegís qué permisos le das. Podés otorgar solo lectura o sumar los de escritura que necesites:

| Scope | Qué permite | Endpoints |
| --- | --- | --- |
| `read` | Sólo lectura | Todos los `GET` de arriba. |
| `links:write` | Crear, actualizar y eliminar links de pago | `POST/PATCH/DELETE /payment-links`. |
| `charges:write` | Crear cobros (checkout) | `POST /payment-links/{id}/checkout`. |
| `subscriptions:write` | Modificar y cancelar suscripciones, abrir el portal | `PATCH /subscriptions/{id}`, `POST /subscriptions/{id}/cancel`, `POST /subscriptions/{id}/portal`. |
| `disputes:write` | Responder disputas con evidencia | `POST /disputes/{id}/response`. |
| `offline_access` | Emitir token de refresco para que la app siga autorizada | — |

Una conexión sin el scope que exige una herramienta recibe `403 insufficient_scope` (en el API v1, con `detail.required_scope` indicando cuál falta).

## Seguridad y revocación

- Los tokens de acceso son **opacos** (`vxo_at_…`), viven 1 hora y se guardan solo hasheados en el servidor.
- El `offline_access` emite un token de refresco (30 días) para re-emitir accesos sin reautorizar.
- Podés ver todas tus apps conectadas y **revocar** su acceso desde **Desarrolladores → Apps conectadas** en el dashboard; al revocar, los tokens de esa app dejan de funcionar.

## Ver también

- [Referencia del API v1](/docs/api) — las operaciones que las herramientas invocan.
- [Modo sandbox](/docs/sandbox-mode) — cómo probar con Stripe test.
- [Especificación OpenAPI](/docs/api/openapi) — la spec con los scopes por operación.