collection-api-refacil MCP Server

Servidor MCP (Model Context Protocol) generado automáticamente para la API collection-api-refacil.

🚀 Características

• 9 herramientas generadas automáticamente desde la colección Postman
• Autenticación flexible: secretId con renovación automática de tokens
• Servidor HTTP con Fastify
• Protocolo MCP estándar para integración con IDEs

📋 Requisitos

• Node.js 20+
• npm o yarn

📦 Instalación desde NPM

Si este paquete está publicado en npm, puedes instalarlo globalmente:

# Instalación global (recomendado)
npm install -g collection-api-refacil-mcp

# Verificar instalación
collection-api-refacil-mcp --version

Configuración Rápida en IDEs

Cursor

1. Abrir Settings → Features → Model Context Protocol
2. Click en "Edit Config"
3. Agregar:

Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

macOS/Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "collection-api-refacil": {
      "command": "collection-api-refacil-mcp",
      "env": {
        "BASE_URL": "https://collection-api.qa.refacil.co",
        "SECRET_ID": "tu-secret-id",
        "AUTH_ENDPOINT": "/auth/jwt",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

4. Reiniciar Cursor

Claude Desktop

Editar archivo de configuración:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "collection-api-refacil": {
      "command": "collection-api-refacil-mcp",
      "env": {
        "BASE_URL": "https://collection-api.qa.refacil.co",
        "SECRET_ID": "tu-secret-id",
        "AUTH_ENDPOINT": "/auth/jwt",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

Reiniciar Claude Desktop.

Visual Studio Code

1. Instalar extensión MCP for VS Code
2. Editar settings.json:

{
  "mcp.servers": {
    "collection-api-refacil": {
      "command": "collection-api-refacil-mcp",
      "env": {
        "BASE_URL": "https://collection-api.qa.refacil.co",
        "SECRET_ID": "tu-secret-id",
        "AUTH_ENDPOINT": "/auth/jwt",
        "TOKEN_CACHE_TTL": "3600"
      }
    }
  }
}

3. Recargar VS Code

🛠️ Instalación para Desarrollo

Si quieres contribuir o ejecutar desde el código fuente:

# Clonar el repositorio
git clone https://github.com/refacil/collection-api-refacil-mcp.git
cd collection-api-refacil-mcp

# Instalar dependencias
npm install

# Construir el proyecto
npm run build

# Iniciar en desarrollo
npm run dev

# Iniciar en producción
npm start

🔧 Configuración

El servidor se configura mediante variables de entorno:

# Copiar archivo de ejemplo
cp .env.example .env

# Editar configuración
nano .env

Variables de Entorno

| Variable | Descripción | Valor por defecto | |----------|-------------|-------------------| | PORT | Puerto del servidor | 3008 | | ENVIRONMENT | Entorno de ejecución | development | | BASE_URL | URL base de la API | https://collection-api.qa.refacil.co | | SECRET_ID | ID secreto para autenticación | 0d92fc6aa394c13... (your secret id) | | AUTH_ENDPOINT | Endpoint de autenticación | /auth/jwt | | TOKEN_CACHE_TTL | TTL del caché de tokens (segundos) | 3600 | | MCP_TOKEN | Token de autenticación del MCP | mcp-secret-token-123 |

🐳 Docker

# Construir imagen
docker build -t collection-api-refacil-mcp .

# Ejecutar contenedor
docker run -p 3008:3008 collection-api-refacil-mcp

# O usar docker-compose
docker-compose up

☸️ Kubernetes

# Aplicar manifests
kubectl apply -f k8s/

# Verificar despliegue
kubectl get pods -l app=collection-api-refacil-mcp

🔌 Uso del MCP

Endpoints Disponibles

• /mcp: Endpoint principal del protocolo MCP
• /health: Health check del servidor
• /tools: Lista de herramientas disponibles

Modo Multi-Usuario (HTTP)

El servidor MCP soporta múltiples usuarios simultáneamente en modo HTTP mediante el header X-Secret-ID.

¿Cómo funciona?

1. Sin X-Secret-ID: Usa el SECRET_ID del archivo .env (modo single-user)
2. Con X-Secret-ID: Usa el secretId proporcionado en el header (modo multi-user)

Ejemplo de uso:

# Usuario 1
curl -X POST http://localhost:3008/mcp \
  -H "Authorization: Bearer mcp-token" \
  -H "X-Secret-ID: user1-secret-id" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {...}}'

# Usuario 2
curl -X POST http://localhost:3008/mcp \
  -H "Authorization: Bearer mcp-token" \
  -H "X-Secret-ID: user2-secret-id" \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/call", "params": {...}}'

Ventajas del Modo Multi-Usuario:

• ✅ Cada usuario usa sus propias credenciales
• ✅ Tokens cacheados por secretId (mejor performance)
• ✅ Un solo servidor para múltiples clientes
• ✅ Compatible con modo single-user (fallback al .env)

🛠️ Herramientas Disponibles

auth_jwt

📌 Overview

To use the Collection API, clients must follow a two-step authentication process:

1. Generate a JWT (Bearer Token) using their Secret ID

2. (Optional) Generate a One-Time Token (OTT) for secure access to specific endpoints

Each request must include the correct headers. Tokens have time-based expiration.

This endpoint allows third-party clients to generate a temporary JWT Bearer token using their assigned Secret ID.

The token is required to authenticate and access protected endpoints in the Collection API.

• The token is valid for 60 minutes.

• You must include the x-secret-id header to request it.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | secretId * | string | Header personalizado: x-secret-id |

auth_one_time_token

📌 Overview

To use the Collection API, clients must follow a two-step authentication process:

1. Generate a JWT (Bearer Token) using their Secret ID

2. (Optional) Generate a One-Time Token (OTT) for secure access to specific endpoints

Each request must include the correct headers. Tokens have time-based expiration.

This endpoint generates a single-use token that provides an extra layer of security for sensitive operations.

• The token is valid for 60 seconds and can only be used once.

• You must include both x-secret-id and Authorization: Bearer headers to request it.

🔐 Endpoints that require One-Time Token

| HTTP Method | Endpoint URL | Description | | --- | --- | --- | | POST | /collection/submit-payment | Registers a payment or top-up at a branch |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | secretId * | string | Header personalizado: x-secret-id | | service | string | Campo del body: service |

collection_submit_payment

Description

This endpoint handles financial transactions and collections. It processes payments, validates customers and companies, and integrates with a payment processing system. The service includes transaction amount validation, customer verification, and company balance management.

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | reference | Integer | ✅ | Unique transaction reference number | | agreementId | Integer | ✅ | ID of the agreement (company) that is making the payment | | amount | Integer | ✅ | Amount to be charged, in COP (Colombian Pesos) | | date | String | ✅ | Transaction date in format YYYY-MM-DD | | time | String | ✅ | Transaction time in format HH:mm (24-hour clock, Bogotá time zone) |

🏢 Available Agreements

| agreementId | Company Name | | --- | --- | | 18252 | Apostar | | 18253 | Susuerte |

⚠️ Only the above agreementIds are currently authorized to use this service.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | secretId * | string | Header personalizado: x-secret-id | | oneTimeToken * | string | Header personalizado: x-one-time-token | | reference | number | Campo del body: reference | | agreementId | number | Campo del body: agreementId | | amount | number | Campo del body: amount | | date | string | Campo del body: date | | time | string | Campo del body: time |

auth_validate

📝Recommendations

• Establish a dedicated QA environment to perform thorough testing before production deployment.

• Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.

• Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

🔐Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token Format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

This endpoint allows you to validate a JWT token by sending an HTTP POST request to {{base_url}}/auth/validate.

Base URL:

| Enviroment | Value | | --- | --- | | QA | https://collection-api.qa.refacil.co | | PROD | https://collection-api.refacil.co |

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | secretId | string | ✅ | The secret identifier used to validate the token. This secretId will be shared by us with the client | | token | string | ✅ | The JWT token to be validated |

📤 Response body parameters

| Field | Type | Description | | --- | --- | --- | | statusCode | number | The HTTP status code of the response | | message | string | A message indicating the result of the operation | | date | number | The timestamp of the response | | payload | object | The response payload containing validation results | | payload.valid | boolean | Indicates whether the token is valid or not | | payload.message | string | A message related to the validation result | | payload.data | object | Optional decoded token data if the token is valid |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | secretId | string | Campo del body: secretId | | token | string | Campo del body: token |

ping

📝Recommendations

• Establish a dedicated QA environment to perform thorough testing before production deployment.

• Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.

• Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

🔐Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token Format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

This endpoint sends an HTTP GET request to {{customer.domain.com}}/ping/ in order to check the availability of the server.

Benefits 🩺

• Fail-fast: detects unavailability before critical operations.

• SLO-aware: monitor per-client availability and trigger mitigations.

• Proactive ops: enables circuit breakers and routing policies.

The request does not contain a request body.

Response

• Status: 200

• Body: "pong"

querybill

📝Recommendations

• Establish a dedicated QA environment to perform thorough testing before production deployment.

• Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.

• Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

🔐Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token Format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

This endpoint allows you to query a bill by sending an HTTP POST request to {{customer.domain.com}}/queryBill/.

Benefits 🔎

• Real-time validation: fresh billing info from the originator.
• Standard error handling: predictable codes/messages simplify UX and support.
• Lower coupling: each client exposes its endpoint; the bridge resolves routing by agreement.
• Observability: traceability via transactionId from query to payment.

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | codCustomer | string | ✅ | The customer code. (Is a constant that identifies us with the supplier) | | reference | string | ✅ | ID of the agreement (company) that is making the payment | | date | string | ✅ | Transaction date in format YYYY-MM-DD | | time | string | ✅ | Transaction time in format HH:mm:ss (24-hour clock, Bogotá time zone) |

📤 Response body parameters

| Field | Type | Description | | --- | --- | --- | | message | string | A message related to the query. | | reference | string | The reference of the bill. | | amount | number | The amount of the bill. | | code | string | The code related to the bill. | | user_code | string | The user code related to the bill. | | additional_data | array | An array of additional data containing label and value pairs. |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | codCustomer | string | Campo del body: codCustomer | | reference | string | Campo del body: reference | | date | string | Campo del body: date | | time | string | Campo del body: time |

submittransaction

📝Recommendations

• Establish a dedicated QA environment to perform thorough testing before production deployment.

• Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.

• Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

🔐Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token Format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

This API endpoint allows you to submit a transaction via an HTTP POST request to {{customer.domain.com}}/submitTransaction/.

Benefits 💳

• Transactional idempotency: transactionId avoids double charges on retries/timeouts.
• Eventual consistency: queues + webhook confirmations reduce manual reconciliation.
• Operational scalability: async processing absorbs traffic spikes.

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | codCustomer | string | ✅ | The customer code. (Is a constant that identifies us with the supplier) | | trasanctionId | string | ✅ | The transaction ID. | | reference | string | ✅ | The reference for the transaction. | | amount | number | ✅ | The amount of the transaction. | | date | string | ✅ | Transaction date in format YYYY-MM-DD | | time | string | ✅ | Transaction time in format HH:mm:ss (24-hour clock, Bogotá time zone) |

📤 Response Body Parameters

| Field | Type | Description | | --- | --- | --- | | message | string | A message regarding the transaction submission. | | reference | string | The reference for the submitted transaction. | | amount | number | The amount of the submitted transaction. | | code | string | A code related to the transaction. | | user_code | string | User-specific code related to the transaction. | | additional_data | array | Additional data associated with the transaction, including label and value pairs. |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | codCustomer | string | Campo del body: codCustomer | | transactionId | string | Campo del body: transactionId | | reference | string | Campo del body: reference | | amount | number | Campo del body: amount | | date | string | Campo del body: date | | time | string | Campo del body: time |

rollbacktransaction

📝Recommendations

• Establish a dedicated QA environment to perform thorough testing before production deployment.

• Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.

• Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

🔐Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token Format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

This API endpoint allows you to submit a transaction via an HTTP POST request to {{customer.domain.com}}/rollbackTransaction/.

Benefits 🔁

• Risk control: safe, auditable reversal for external failures/inconsistencies.
• Full traceability: reversal events and contingency log.
• Business continuity: formal channel for emergencies without invasive manual actions.

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | codCustomer | string | ✅ | The customer code. (Is a constant that identifies us with the supplier) | | transactionId | string | ✅ | The transaction ID. | | reference | string | ✅ | The reference for the transaction. | | amount | number | ✅ | The amount of the transaction. | | date | string | ✅ | Transaction date in format YYYY-MM-DD | | time | string | ✅ | Transaction time in format HH:mm:ss (24-hour clock, Bogotá time zone) |

📤 Response Body Parameters

| Field | Type | Description | | --- | --- | --- | | message | string | A message indicating the status of the rollback process. | | reference | string | The reference number of the transaction. | | amount | number | The amount of the transaction. | | code | string | A status code for the rollback process. | | user_code | string | A user-specific code related to the rollback process. | | additional_data | (array) | An array containing additional information about the rollback, including label and value pairs. |

Parámetros:

| Name | Type | Description | | --- | --- | --- | | codCustomer | string | Campo del body: codCustomer | | transactionId | string | Campo del body: transactionId | | reference | string | Campo del body: reference | | amount | number | Campo del body: amount | | date | string | Campo del body: date | | time | string | Campo del body: time |

webhook

📝Recommendations

• Establish a dedicated QA environment to perform thorough testing before production deployment.

• Set a minimum timeout of 60 milliseconds for API requests to handle longer processes reliably.

• Provide clear and standardized error mapping, detailing error codes, messages, and causes for better troubleshooting.

🔐Authorization

To establish a secure connection with our clients' APIs, we will generate and provide you with an authorization token. This token will allow us to authenticate with the API that our clients build.

Token Format:

Authorization: Token {generate_token_value}

Example:

Authorization: Token eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9**

This endpoint allows you to receive transaction notifications processed by the payment system. The merchant must implement this endpoint to receive transaction status updates.

Benefits 🔔

• Push notifications: eliminates polling, reduces cost and update latency.
• Security: signature/auth validation for trusted origin.
• Robust delivery: retries, backoff and DLQ (if applicable) ensure reception.
• Simple integration: compact contract (status/timestamps/ids), quick to implement.

📥 Request Body Parameters

| Field | Type | Required | Description | | --- | --- | --- | --- | | realAmount | number | ✅ | Real transaction amount (without costs) | | amount | number | ✅ | Total transaction amount (including costs) | | cost | string | ✅ | Total transaction cost | | referenceId | string | ✅ | Unique transaction identifier | | customerReference | string | ✅ | Customer reference provided during the transaction | | updatedAt | string | ✅ | Date and time of last update (format: "YYYY-MM-DD HH:mm:ss") | | status | number | ✅ | Transaction status ID : 1 Pending , 2 Approved ,3 Failed | | sign | string | ✅ | Security signature to validate message integrity |

📤 Response Body Parameters

| Field | Type | Description | | --- | --- | --- | | statusCode | number | HTTP status code of the response | | message | string | Message indicating the operation result | | date | number | Response timestamp | | payload | object | Response payload (optional) |

🔐 Security Validation

The sign field must be validated to ensure message integrity. The signature is generated by concatenating the following fields:

let signature = referenceId-customerReference-amount-updatedAt-HASH_KEY;
signature = crypto.createHmac("sha1", HASH_KEY).update(signature).digest("hex");

Note: The HASH_KEY will be shared by us during the integration process to ensure secure communication between systems.

Parámetros:

| Name | Type | Description | | --- | --- | --- | | realAmount | number | Campo del body: realAmount | | amount | number | Campo del body: amount | | cost | string | Campo del body: cost | | referenceId | string | Campo del body: referenceId | | customerReference | string | Campo del body: customerReference | | updatedAt | string | Campo del body: updatedAt | | status | number | Campo del body: status | | sign | string | Campo del body: sign |

📝 Logs

El servidor genera logs detallados de todas las operaciones:

[2024-01-01T12:00:00.000Z] get_users iniciada
[2024-01-01T12:00:01.000Z] get_users completada exitosamente

🔍 Troubleshooting

Error de autenticación

Verificar que las credenciales estén configuradas correctamente en las variables de entorno.

Error de conexión a la API

Verificar que BASE_URL sea accesible y la API esté funcionando.

Error de puerto

Verificar que el puerto 3008 no esté siendo usado por otro servicio.

📞 Soporte

Para soporte técnico, contactar al equipo de desarrollo.

Generado automáticamente por Refacil MCP Framework