Documentación

Servidor MCP

El servidor MCP expone las operaciones de cobro como herramientas para Claude, ChatGPT, Cursor o cualquier cliente Model Context Protocol. Cada herramienta reentra al mismo handler /v1.

Endpoints

Entorno	URL	Credencial
Pruebas	`https://api.pagos.express/mcp/test`	`sk_test_…` o OAuth con alcance `pagos:test`
En vivo	`https://api.pagos.express/mcp`	`sk_live_…` o OAuth con alcance `pagos:live`

Transporte Streamable HTTP sin sesiones: POST con Accept: application/json, text/event-stream. GET y DELETE responden 405.
El entorno lo define la credencial, nunca un argumento. Una clave de prueba contra el endpoint en vivo recibe 403.
Descubrimiento OAuth en https://api.pagos.express/.well-known/oauth-protected-resource/mcp/test, …/oauth-protected-resource/mcp y https://api.pagos.express/.well-known/oauth-authorization-server.

Conectar un cliente

En el dashboard abre API y MCP: ahí está la URL del entorno seleccionado y un ejemplo del encabezado.
Agrega un servidor MCP remoto en tu cliente con esa URL. Si el cliente admite OAuth, elígelo: iniciarás sesión en Pagos Express y verás una pantalla de consentimiento con el cliente, el entorno y los permisos (incluido el envío de correo).
Si el cliente solo acepta un Bearer estático, usa una clave API en su configuración secreta. Nunca la pegues en el prompt.
Revoca el acceso de un agente cuando quieras en Agentes conectados. Eso invalida sus tokens actuales.

Ejemplo de configuración con clave (formato orientativo)

{
  "mcpServers": {
    "pagos-express": {
      "url": "https://api.pagos.express/mcp/test",
      "headers": { "Authorization": "Bearer sk_test_..." }
    }
  }
}

Herramienta	REST	Para qué sirve
`create_payment_link`	`POST /v1/payment_links`	Crea un cobro con conceptos e importes. Devuelve la URL para compartir; no cobra ni envía correo por sí solo.
`list_payment_links`	`GET /v1/payment_links`	Lista los enlaces del entorno actual, con paginación por cursor.
`get_payment_link`	`GET /v1/payment_links/{id}`	Consulta un enlace y su estado.
`disable_payment_link`	`POST /v1/payment_links/{id}/disable`	Desactiva un enlace. No reembolsa pagos ya cobrados.
`update_payment_link`	`POST /v1/payment_links/{id}`	Edita título, descripción, datos del cliente o si es facturable un enlace activo. Conceptos e importes no cambian.
`mark_payment_link_paid`	`POST /v1/payment_links/{id}/mark_paid`	Registra un pago recibido fuera del checkout (transferencia, efectivo). Cierra el enlace y dispara los webhooks. Pide confirmación al usuario.
`list_payments`	`GET /v1/payments`	Lista pagos. Solo el estado succeeded confirma fondos recibidos.
`get_payment`	`GET /v1/payments/{id}`	Consulta el estado de un pago concreto.
`sync_payment`	`POST /v1/payments/{id}/sync`	Verifica el pago con su pasarela y actualiza el estado.
`send_payment_link_email`	`POST /v1/payment_links/{id}/email`	Envía el enlace por correo si el usuario lo autoriza. En pruebas no se entrega correo real.
`list_payment_link_emails`	`GET /v1/payment_links/{id}/emails`	Consulta las últimas entregas de correo de un enlace.
`list_connections`	`GET /v1/connections`	Lista proveedores conectados. No expone credenciales.
`get_invoicing_connection`	`GET /v1/invoicing/connection`	Consulta la conexión con CFDI Express y el emisor (RFC) que factura.
`get_invoicing_catalogs`	`GET /v1/invoicing/catalogs`	Catálogos SAT de régimen fiscal y uso de CFDI para validar los datos del receptor.
`get_payment_invoice`	`GET /v1/payments/{id}/invoice`	Consulta si un pago se puede facturar, el enlace de autofacturación y su factura.
`invoice_payment`	`POST /v1/payments/{id}/invoice`	Timbra el CFDI de un pago con los datos fiscales del cliente. Confirma los datos con el usuario.
`get_payment_invoice_files`	`GET /v1/payments/{id}/invoice/files`	Devuelve el PDF y el XML de la factura (enlaces que caducan en 15 minutos).
`cancel_payment_invoice`	`POST /v1/payments/{id}/invoice/cancel`	Pide al SAT cancelar la factura de un pago. Pide autorización al usuario; no reembolsa.

Ninguna herramienta inicia el checkout del cliente, reembolsa, crea claves API ni conecta proveedores. Los resultados nunca incluyen secretos. Los importes van en centavos enteros y solo succeeded confirma un pago.

OAuth para agentes

Registro dinámico de clientes en /auth/mcp/register; autorización con PKCE S256 y un único resource igual a la URL del servidor MCP.
El servidor añade el alcance del entorno (pagos:test o pagos:live) más pagos:email y siempre pide consentimiento.
Tokens de acceso de una hora; con offline_access, refresh de 30 días con rotación serializada.
Los tokens OAuth sirven en las operaciones REST de la tabla anterior; consulta Autenticación y modos.

Endpoints

Conectar un cliente

Herramientas

OAuth para agentes