MyFatoorah MCP

Un servidor del Model Context Protocol compatible con LLM para la API de MyFatoorah. Permite que Claude, VS Code, Cursor y otros hosts MCP descubran métodos de pago, creen enlaces de pago, verifiquen pagos, consulten facturas y gestionen reembolsos mediante herramientas específicas.

Este es un proyecto comunitario independiente, no un producto oficial de MyFatoorah. Prueba en el sandbox antes de usar una cuenta real.

Para la configuración paso a paso del host, pruebas con Inspector, prompts para agentes, verificación de pagos, reembolsos y solución de problemas, consulta la guía de uso.

Requisitos

• Node.js 20 o superior

• Un token de API de MyFatoorah con únicamente los permisos requeridos por las herramientas que uses

Related MCP server: AgentPay

Configuración

npm install
cp .env.example .env
npm run build

Establece MYFATOORAH_API_TOKEN en el entorno del host MCP. El servidor no carga .env automáticamente; la configuración de depuración de VS Code sí lo hace.

Variables de entorno

Kuwait también cubre el origen de API compartido de Baréin, Jordania y Omán. Las cuentas multipaís usan un token separado para cada país.

Conectar un host MCP

Usa una ruta absoluta en las configuraciones del host. Reemplaza /absolute/path/to/myfatoorah-mcp y el marcador de posición del token localmente.

Claude Desktop

Añade este servidor a la configuración MCP de Claude Desktop:

{
  "mcpServers": {
    "myfatoorah": {
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}

Reinicia Claude Desktop después de guardar la configuración.

Claude Code

La configuración a nivel de proyecto puede usar .mcp.json (no lo confirmes si contiene un token):

{
  "mcpServers": {
    "myfatoorah": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/myfatoorah-mcp/dist/index.js"],
      "env": {
        "MYFATOORAH_API_TOKEN": "YOUR_TOKEN",
        "MYFATOORAH_ENVIRONMENT": "test"
      }
    }
  }
}

VS Code / GitHub Copilot

El .vscode/mcp.json incluido inicia el servidor compilado y solicita un token de forma segura. Compila una vez, abre la vista de servidores MCP y luego inicia myfatoorah. El token no se almacena en el repositorio.

Cursor y hosts stdio genéricos

Usa los mismos valores command, args y env que en el ejemplo de Claude Desktop. Los mensajes del protocolo MCP usan stdin/stdout; los diagnósticos del servidor deben usar stderr.

Después de publicar en npm, los hosts pueden iniciarlo con npx -y myfatoorah-mcp.

Herramientas

El servidor también expone:

• Recurso myfatoorah://configuration: entorno, URL base, tiempo de espera y si hay un token configurado; nunca el token en sí.

• Prompt create-payment-safely: un flujo de trabajo reutilizable y guiado para enlaces de pago.

Las herramientas exitosas devuelven un resumen de texto conciso más structuredContent legible por máquina que contiene la respuesta de MyFatoorah.

Flujo de pago seguro

1. Lee myfatoorah://configuration y confirma si es prueba o producción.

2. Si eliges una pasarela, llama a myfatoorah_get_payment_methods y usa su ApiName.

3. Confirma el importe, la moneda, el cliente, el método de notificación y la URL de devolución de llamada.

4. Llama a myfatoorah_create_payment y entrega al cliente su PaymentURL.

5. Después de la devolución de llamada, llama a myfatoorah_get_payment con el PaymentId devuelto. Una redirección no es prueba de pago; exige el estado de factura PAID y el estado de transacción SUCCESS.

Los reembolsos mueven dinero en modo producción. Obtén la aprobación explícita del usuario para el PaymentId y el importe exactos antes de pasar confirm: true.

Desarrollo

npm run format
npm run lint
npm run typecheck
npm test
npm run build
npm run inspect

npm run inspect inicia el Inspector MCP oficial contra el servidor stdio compilado. VS Code también incluye tareas de compilación/pruebas y una configuración de depuración.

Las pruebas simulan todas las solicitudes a MyFatoorah; no hacen llamadas de red ni requieren un token.

Seguridad

• Usa una clave API de MyFatoorah con privilegios mínimos y gírala con regularidad.

• Coloca las credenciales en el entorno del host o en un administrador de secretos; nunca en el control de versiones ni en el contexto del modelo.

• La herramienta de solicitud genérica rechaza URLs absolutas, URLs relativas a protocolo, traversal y rutas fuera de /v2/ y /v3/ para evitar la exfiltración de credenciales.

• Los errores de API y los valores Bearer se redactan antes de llegar al modelo.

• Prefiere claves de idempotencia para las mutaciones compatibles e identificadores de pedido estables.

• No expongas este proceso stdio como un servicio de red sin autenticación.

• El manejo directo de tarjetas no se modela intencionadamente como una herramienta específica; requiere cumplimiento PCI.

Alcance de la API y referencias

Las herramientas específicas usan las rutas v3 documentadas de MyFatoorah a partir de agosto de 2026:

• GET /v3/payment-methods

• POST /v3/payments

• GET /v3/payments/{paymentId}

• GET /v3/invoices/{invoiceId}

• GET /v3/invoices/externalIdentifier/{externalIdentifier}

• POST /v3/refunds

• GET /v3/refunds/{refundId}

Referencias:

• Clave de API y URLs regionales de MyFatoorah

• MCP TypeScript SDK v2

• Especificación del Model Context Protocol

Licencia

MIT