# MCP para comercios

El MCP de Fluxis permite que un asistente cree links de pago, checkouts alojados y pagos cripto directos con tu clave de API. Habla [Streamable HTTP](https://modelcontextprotocol.io) y no guarda sesión.

## Endpoints

| Ambiente | URL | Prefijo de la clave |
| -------- | --- | ------------------- |
| Local | `http://localhost:8080/mcp` | `fxs.dev.` |
| Sandbox (staging) | `https://mcp.stgfluxis.us/mcp` | `fxs.stg.` |
| Producción | `https://mcp.fluxis.us/mcp` | `fxs.prd.` |

`GET /.well-known/mcp/server-card.json` describe el servidor cuando el MCP está activo. `GET` y `DELETE` sobre `/mcp` responden 405.

Sandbox es el despliegue de staging sobre mainnet. Un cobro en sandbox es un pago real. Usa montos chicos. No hay simulador de pagos.

## Autenticación

Envía la misma clave que usas en la API REST:

- `x-fluxis-api-key` y `x-fluxis-api-secret`, o
- `Authorization: Bearer <clave>:<secreto>`

El prefijo de la clave tiene que coincidir con el host. Una clave de producción en el host de sandbox se rechaza.

| Rol | Acceso MCP |
| --- | ---------- |
| `read` | Solo tools de lectura (`payments:read`) |
| `write` | Lectura y tools de creación o borrado (`payments:read` y `payments:write`) |

Una credencial inválida responde `401` con `{"error":"invalid_token","error_description":"..."}` y `WWW-Authenticate: Bearer realm="fluxis"`. OAuth no está disponible.

Cada tool comprueba que el punto de venta pertenezca a la credencial. Una clave de cuenta ve solo esa cuenta. Una clave de organización ve las cuentas de su alcance.

## Tools

Llama primero a `fluxis_get_context`.

| Tool | Acceso | Para qué |
| ---- | ------ | -------- |
| `fluxis_get_context` | lectura | Ambiente, dueño de la clave, cada punto de venta y si acepta links y checkout, y el POS online por defecto |
| `fluxis_list_points_of_sale` | lectura | Puntos de venta que esta clave puede usar |
| `fluxis_list_payment_links` | lectura | Links de pago. El estado por defecto es `active` |
| `fluxis_get_payment_link` | lectura | Un link por id o por código, con estadísticas y cinco pagos recientes |
| `fluxis_get_payment` | lectura | Un pago por id, o el más nuevo de una referencia |
| `fluxis_list_payments` | lectura | Pagos. Ventana por defecto: últimos 30 días UTC, máximo 92 |
| `fluxis_list_transactions` | lectura | Movimientos del libro después de confirmar un pago |
| `fluxis_get_payment_options` | lectura | Activos cripto que acepta el punto de venta |
| `fluxis_create_payment_link` | escritura | Link reusable para compartir con compradores |
| `fluxis_delete_payment_link` | escritura | Borrado lógico en dos pasos |
| `fluxis_create_checkout` | escritura | Página de checkout de un solo uso |
| `fluxis_create_crypto_payment` | escritura | Solicitud de pago cripto directo |

### Campos del link de pago

`name` es el nombre que ve el comprador. `buyer_reference` es tu referencia interna de orden o factura. El comprador no la ve como título del producto. En la API REST el mismo campo se llama `external_id`.

Si omites `expiration` y `expires_in_minutes`, el link no vence. Envía como máximo uno de los dos. `expires_in_minutes` va de 5 a 43200. `expiration` es una marca RFC3339 en el futuro.

### Confirmación de borrado

La primera llamada a `fluxis_delete_payment_link` no borra el link. Devuelve un `confirmation_token` que dura 300 segundos. Pide confirmación al usuario y vuelve a llamar la tool con ese token. Borrar un link que ya está borrado responde `already_deleted`.

### Idempotencia y límites

Pasa `idempotency_key` (8 a 64 letras, dígitos, `_` o `-`) en las creaciones. La misma clave y la misma entrada repiten el resultado original durante 24 horas. La misma clave con otra entrada responde conflicto.

Por credencial y por minuto: 120 lecturas, 20 escrituras y 10 borrados. Una tool limitada responde `RATE_LIMITED` y `retry_after_seconds`.

## Recursos y prompts

- `fluxis://docs/quickstart`
- `fluxis://docs/payment-statuses`
- `fluxis://catalog/payment-options`
- `fluxis://payments/{payment_id}`
- Prompts: `fluxis_charge_customer`, `fluxis_integrate`, `fluxis_sales_summary`

Los links de pago también están en la API REST. Ver [Links de pago](/es/docs/developers/payment-links).