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 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-keyyx-fluxis-api-secret, oAuthorization: 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/quickstartfluxis://docs/payment-statusesfluxis://catalog/payment-optionsfluxis://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.