nhcx-payer-mcp

MCP server to simulate NHCX payer-side actions. After a provider (e.g., Nice HMS) submits a preauth or claim to NHCX, use this tool to act as the mock payer — approve, reject, query, or forward cases through the full payer workflow.

Designed for external integrators testing their NHCX provider integration. No more dependency on NHA teams for payer-side workflow actions.

Quickstart

# 1. Set your credentials (required)
export NDHM_CLIENT_ID=SBX_000XXX
export NDHM_CLIENT_SECRET=your-sandbox-secret

# 2. Configure your test defaults (optional but recommended)
export PAYER_ID=1518
export SENDER_CODE=1000000001
export MEMBER_ID=your-test-patient-id

# 3. Run via npx (no install needed)
npx nhcx-payer-mcp

# Or install globally
npm install -g nhcx-payer-mcp
nhcx-payer-mcp

Related MCP server: Constructoo MCP Server

MCP Host Configuration

Add to your MCP host (Claude Desktop, VS Code, etc.):

{
  "mcpServers": {
    "nhcx-payer": {
      "command": "npx",
      "args": ["nhcx-payer-mcp"],
      "env": {
        "NDHM_CLIENT_ID": "SBX_000XXX",
        "NDHM_CLIENT_SECRET": "your-sandbox-secret",
        "PAYER_ID": "1518",
        "SENDER_CODE": "1000000001",
        "MEMBER_ID": "your-test-patient-id"
      }
    }
  }
}

Environment Variables

Required

Optional — Defaults

Optional — URL Overrides

Override individual API base URLs (takes precedence over NHCX_ENV):

Tools

nhcx_validate_config

Validate your setup. Checks all env vars, tests authentication, and verifies API URL reachability. Run this first.

Input:  (none)
Output: { ok, result: { valid, issues[], config, connectivity } }

nhcx_login

Authenticate with ABDM gateway V3 and cache a token (15 min). All tools auto-authenticate — this is a convenience for connectivity checks.

Input:  (none)
Output: { ok, result: { clientId, tokenPrefix, cachedFor } }

nhcx_get_user_role

Get the current payer role and allowed actions for a case. Always call this before processing.

Input:  caseId (required), payerId (optional, default from env)
Output: { ok, result: { caseId, role, allowedActions[], rawResponse } }

nhcx_process_case

Execute a payer action on a case. The usecase is derived automatically from the action. Valid actions are validated before the API call.

Input:  caseId (required)
        action (required) — Approve, Reject, Query, Forward, Pending,
                             cpdApprove, cpdReject, iQuery
        senderCode (required) — provider/sender code
        memberId (required) — patient ABHA/PMJAY ID
        receiverCode (optional, default from env)
        remarks (optional, default "ok")
        correlationId (optional, auto-generated)
Output: { ok, result: { caseId, action, usecase, role, correlationId, rawResponse } }

nhcx_workflow

Show the full payer workflow with steps, usecase per step, roles, and allowed actions.

Input:  (none)
Output: { ok, result: { workflow: [...] } }

Payer Workflow

Testing Workflow Example

1. Validate config: nhcx_validate_config

2. Check role: nhcx_get_user_role(caseId: "2026072210000472")

3. Process case: nhcx_process_case(caseId: "...", action: "Approve", senderCode: "...", memberId: "...")

For CLAIM workflow, repeat steps 2-3 through all 6 steps in sequence.

Troubleshooting

"NDHM_CLIENT_ID and NDHM_CLIENT_SECRET must be set" Set both env vars. For sandbox testing, get credentials from NHA.

"Unknown action" Action names are case-sensitive. Use exact casing: Approve, Reject, Query, Forward, Pending, cpdApprove, cpdReject, iQuery.

"HTTP 401" or auth errors Your credentials are wrong or expired. Run nhcx_validate_config to check.

Tool hangs Check NHCX_TIMEOUT — default is 30s. Set DEBUG=true for request logging.

Sandbox URLs changed Override with NHCX_USER_ROLE_URL and NHCX_PROCESS_CASE_URL env vars.

License

MIT