Abhi Open API MCP Server

MCP (Model Context Protocol) server for the Abhi Open API (EWA - UAE). Exposes all 28 API endpoints as tools that AI agents can invoke through natural language.

Installation

npm install -g @abhi-finance/mcp-server-open-api

Or use directly with npx:

npx @abhi-finance/mcp-server-open-api

From Source

npm install
npm run build

Getting Credentials

This MCP server requires API credentials to connect to Abhi's platform. To obtain credentials, please get in touch with the Abhi UAE team. They will provide you with:

• API base URL and login URL for your environment (UAT/Production)
• Username (email) and password
• MFA setup (if applicable)

Without valid credentials, the server cannot authenticate with the Abhi API.

Configuration

Environment Variables

| Variable | Required | Description | | ---------------------- | -------- | -------------------------------------- | | ABHI_API_BASE_URL | Yes | API host (no trailing path) | | ABHI_API_LOGIN_URL | Yes | Full login endpoint URL | | ABHI_API_PREFIX | Yes | Path prefix for all API calls | | ABHI_API_USERNAME | Yes | Login email | | ABHI_API_PASSWORD | Yes | Login password | | ABHI_API_MFA | No | MFA TOTP code (if MFA enabled) | | ABHI_API_EMIRATES_ID | No | Emirates ID (for employee-level login) |

Environment Examples

UAT:

ABHI_API_BASE_URL=https://api-uat-v2.abhi.ae
ABHI_API_LOGIN_URL=https://api-uat-v2.abhi.ae/uat-auth/external/login
ABHI_API_PREFIX=/uat-open-api

Usage

Add to your MCP client settings (e.g., mcp.json in your workspace):

Using npx (recommended after npm install)

{
  "mcpServers": {
    "abhi-open-api": {
      "command": "npx",
      "args": ["@abhi-finance/mcp-server-open-api"],
      "env": {
        "ABHI_API_BASE_URL": "https://api-uat-v2.abhi.ae",
        "ABHI_API_LOGIN_URL": "https://api-uat-v2.abhi.ae/uat-auth/external/login",
        "ABHI_API_PREFIX": "/uat-open-api",
        "ABHI_API_USERNAME": "[email protected]",
        "ABHI_API_PASSWORD": "your-password"
      }
    }
  }
}

Using local path

{
  "mcpServers": {
    "abhi-open-api": {
      "command": "node",
      "args": ["/full/path/to/open-api-mcp/dist/index.js"],
      "env": {
        "ABHI_API_BASE_URL": "https://api-uat-v2.abhi.ae",
        "ABHI_API_LOGIN_URL": "https://api-uat-v2.abhi.ae/uat-auth/external/login",
        "ABHI_API_PREFIX": "/uat-open-api",
        "ABHI_API_USERNAME": "[email protected]",
        "ABHI_API_PASSWORD": "your-password"
      }
    }
  }
}

After saving, reconnect MCP servers in your IDE.

Available Tools (28)

1. Authentication

• login — Authenticate and obtain JWT token (24hr validity)

2. Employee Management

• employees_operation — Unified create/update/balance endpoint (upsert by emiratesId)
• get_all_employees — List employees with pagination and filters
• add_employees — Batch create employees
• update_employees — Batch update employees (bankId required in payload)
• delete_employees — Soft-delete by Emirates ID
• employee_eligibility_check — Pre-onboarding eligibility assessment

3. Transaction Operations

• validate_employee_transaction — Pre-transaction fee check (employer token)
• validate_transaction_employee_token — Pre-transaction check (employee token)
• create_transaction — Create EWA/Salary Advance transaction
• post_transaction_employee_token — Post transaction (employee token)
• get_transaction_status — Get status and signed agreement URL
• get_all_transactions — List all org transactions with filters
• get_employee_transaction_history — Employee transaction history (employee token)
• get_monthly_balance — Employee available balance (employee token)
• cancel_transaction — Cancel transaction (irreversible)

4. Repayment

• get_outstanding_balance — Outstanding repayment info by Emirates ID
• post_repayment — Submit loan repayment (enters PENDING state)

5. Organization Management

• get_all_sub_organizations — List sub-organizations
• create_sub_organization — Create sub-organization

6. Reference Data

• get_all_banks — Bank directory (use bank IDs when creating employees)
• get_all_business_types — Business type directory
• get_media_signed_url — Pre-signed S3 upload/download URL

7. Assessment & Verification

• validate_questions_key_value — Financial assessment (A1-A4 format)
• validate_questions_array — Financial assessment (dynamic questions)

8. Term Loans

• check_term_loan_eligibility — Check eligibility, returns trackingId
• create_term_loan — Create term loan (requires trackingId from eligibility)
• repay_term_loan — Submit term loan repayment
• get_active_term_loan — Get active loans with schedules

Important Notes

Mawarid-Enabled Organizations

If the organization has Mawarid enabled, employee creation requires additional fields:

• emiratesIdExpiryDate, emiratesIdNationality, emiratesIdDateOfBirth, emiratesIdFullName, emiratesIdGender, emiratesIdCardNumber, emiratesIdIdentificationNumber
• acceptedTnCs, providedInformationConsent, KFSConsent
• fullName, employerName, doYouIdentifyAsAPersonOfDetermination
• basicIncome, customerIBAN, areYouAPoliticallyExposedPerson, street1
• mxDocuments — array with format: [{label: "Emirates ID Front", filePath: "url"}, {label: "Emirates ID Back", filePath: "url"}]

API-Specific Requirements

• update_employees: bankId is mandatory in the payload (server returns 500 without it)
• validate_employee_transaction: Include confirmPromiseToPurchase: true if Mawarid/promise-to-purchase is enabled
• create_transaction: Include agreementAccepted: true on Mawarid-enabled orgs
• employee_eligibility_check: All date fields must be ISO 8601 format (e.g., "2025-11-30T00:00:00.000Z")
• create_term_loan: Must call check_term_loan_eligibility first and pass the trackingId from its response
• Employee-level endpoints (history, balance, validate/post by employee token): Require login with emiratesId to get an employee-level token

Auth Flow

The server handles authentication transparently:

1. On first API call, it logs in using configured credentials
2. JWT token is cached in memory
3. Token is auto-refreshed 5 minutes before expiry
4. No manual login step needed

Architecture

AI Agent ──stdio──▶ MCP Server (Node.js) ──HTTPS──▶ Abhi API (AWS)

• Communication: JSON-RPC over stdin/stdout
• Auth: JWT Bearer token (auto-managed)
• Validation: Zod schemas on all inputs
• Runtime: Node.js ES Modules

Project Structure

open-api-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── http-client.ts        # HTTP client with auto-auth
│   └── tools/
│       ├── auth.ts           # login
│       ├── employees.ts      # 6 employee tools
│       ├── transactions.ts   # 9 transaction tools
│       ├── repayments.ts     # 2 repayment tools
│       ├── organizations.ts  # 2 org tools
│       ├── reference.ts      # 3 reference data tools
│       ├── assessment.ts     # 2 assessment tools
│       └── term-loans.ts     # 4 term loan tools
├── openapi.yaml              # OpenAPI 3.0.3 spec
├── package.json
├── tsconfig.json
└── dist/                     # Compiled output

Security

• Credentials stored in environment variables only (never in code)
• Token cached in process memory (not persisted to disk)
• Server runs locally — communication is stdio, no network exposure
• Each user needs their own credentials configured

OpenAPI Spec

The full OpenAPI 3.0.3 specification is available at openapi.yaml in this directory.