How do I use nhcx-payer-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@nhcx-payer-mcp Approve preauth case 2026072210000472" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

nhcx-payer-mcp

by umeshramya

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

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
export REAL_ABHA=12345678901234
export DUMMY_ABHA=12345678904321

# 3. Run via npx (no install needed)
#    @latest guarantees you get the newest published version (npx caches by version)
npx nhcx-payer-mcp@latest

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

Related MCP server: mock-llm-mcp

MCP Host Configuration

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

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

Environment Variables

Required

Variable	Description
`NDHM_CLIENT_ID`	ABDM gateway client ID (sandbox: `SBX_000XXX`)
`NDHM_CLIENT_SECRET`	ABDM gateway client secret

Optional — Defaults

Variable	Default	Description
`NDHM_URL`	`https://dev.abdm.gov.in`	ABDM gateway auth URL
`NHCX_ENV`	`sandbox`	Environment: `sandbox`, `staging`, `production`
`PAYER_ID`	`1518`	Your payer code (used as `receivercode` in API calls)
`SENDER_CODE`	—	Default provider/sender code for testing
`MEMBER_ID`	—	Default patient ABHA/PMJAY member ID for testing
`REAL_ABHA`	—	Default real ABHA number for `nhcx_update_abha_number`
`DUMMY_ABHA`	—	Default dummy ABHA number for `nhcx_update_abha_number`
`NHCX_TIMEOUT`	`30000`	API request timeout in milliseconds
`NHCX_RETRIES`	`0`	Auto-retries on transient errors (5xx, network)
`DEBUG`	`false`	Set to `true` for debug logging to stderr

Optional — URL Overrides

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

Variable	Description
`NHCX_USER_ROLE_URL`	Base URL for get/user-role endpoint
`NHCX_PROCESS_CASE_URL`	Base URL for process/case endpoint

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) — numeric ID or full prefixed format
                             (e.g. "2026081210000359" or "PMJAY/HP/S/2024/R2/2026081210000359")
                             Prefix is auto-stripped for process/case API compatibility.
        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 (required) — from original submission, never 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: [...] } }

`nhcx_update_abha_number`

Map a real ABHA number to a dummy ABHA number for cyclic-procedure claim testing. Replaces the real ABHA captured during biometric authentication with the dummy ABHA used in the claim, so claim validation can locate the dummy beneficiary's biometric records. For lower/test environments only.

Input:  realAbha (required) — real ABHA number captured during biometric auth
        dummyAbha (required) — dummy ABHA number used in the claim request
        (both default from REAL_ABHA / DUMMY_ABHA env vars)
Output: { ok, result: { realAbha, dummyAbha, rawResponse } }

Payer Workflow

Step	Usecase	Role	Actions
0	PREAUTH	PPD-Trust	Approve, Reject, Query
1	CLAIM	CEX-Trust	Forward
2	CLAIM	CPD-Trust	Pending, cpdApprove, cpdReject
3	Medical Audit Committee	Medical Audit Committee	Approve, Reject, iQuery
4	CLAIM	ACO-Trust	Approve, Reject, Pending
5	CLAIM	SHA-Trust	Approve, Reject, Pending
6	Claim Review Committee	Claim Review Committee	Approve, Reject, Pending

Testing Workflow Example

Validate config: nhcx_validate_config
Check role: nhcx_get_user_role(caseId: "2026072210000472")
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

Available Tools

5 tools

nhcx_get_user_roleA

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

ParametersJSON Schema

Name	Required	Description	Default
`caseId`	Yes	Case number / ID
`payerId`	No	Payer ID	1518

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It indicates that the tool 'gets' role and allowed actions, but does not disclose side effects (e.g., read-only), authentication requirements, rate limits, or error behavior. The 'Always call' note is workflow guidance rather than behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: one states the purpose, the other gives a clear directive. Every word earns its place, and the critical usage note is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 2-parameter tool with no output schema, the description explains what is returned (role and allowed actions) and when to call it (before processing). It lacks mention of prerequisites like login, but the sibling list includes nhcx_login, and the core information is sufficient for most use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for both parameters, so the description adds little beyond the schema. The phrase 'for a case' maps to caseId, but no new meaning is added for payerId or the parameters in general. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and clearly identifies the resource ('current payer role for a case and the allowed actions for that role'). This distinguishes it from sibling tools like nhcx_login (auth) and nhcx_process_case (processing), making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The instruction 'Always call this before processing a case' provides clear context on when to use the tool relative to processing a case. However, it does not mention when not to use it or explicitly name alternatives, so it falls slightly short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nhcx_loginA

Authenticate with the ABDM gateway V3 and cache a session token (15 min). Useful as a connectivity check — all other tools auto-authenticate.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the authentication action, token caching, and a 15-minute timeout, which is valuable. However, it does not explain what happens on failure, whether an existing token is overwritten, or any potential side effects beyond caching.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is exactly two sentences, front-loaded with the core purpose and followed by the use case. Every phrase adds value, with no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter tool with no output schema, the description effectively covers purpose, usage guidance, and a key behavioral detail (token lifetime). It could mention the return value or prerequisites, but the note that other tools auto-authenticate makes the overall context sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema provides complete information. Per the rubric, a baseline of 4 is appropriate since there is nothing for the description to add about parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Authenticate with the ABDM gateway V3 and cache a session token (15 min).' It uses a specific verb and resource, and distinguishes itself from siblings by noting 'all other tools auto-authenticate', making its purpose unique.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Useful as a connectivity check' and 'all other tools auto-authenticate', providing both a recommendation for when to use it and an implicit exclusion for normal operations. This is clear guidance versus alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nhcx_process_caseB

Act as a payer and perform an action on a case: Approve, Reject, Query, Forward, Pending, cpdApprove, cpdReject, iQuery. The usecase is derived automatically from the action. The caseId, action, senderCode, memberId, and correlationId are required.

ParametersJSON Schema

Name	Required	Description	Default
`action`	Yes	Action: Approve, Reject, Query, Forward, Pending, cpdApprove, cpdReject, iQuery
`caseId`	Yes	Case number
`remarks`	No	Remarks / reason for action	ok
`memberId`	Yes	Patient ABHA/PMJAY member ID
`senderCode`	Yes	Provider/sender code
`receiverCode`	No	Payer code	1518
`correlationId`	Yes	Correlation ID from the original submission (required — never guess this)

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It mentions that the usecase is derived automatically, but does not disclose side effects, irreversibility, authentication requirements, or return format. For a tool that can approve/reject cases, this is a significant transparency gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at two sentences, front-loading the main purpose and action list. The second sentence efficiently lists required parameters. No fluff or redundant information, though the structure could be slightly improved with a clearer separation of purpose and usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool performs case mutations and there is no output schema or annotations, the description is incomplete. It lacks information about expected responses, error handling, pre-conditions (e.g., login), or post-condition effects. The schema covers parameters but not behavior, and the short description does not compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal semantic value beyond the schema, simply restating that certain parameters are required. The schema already provides clear descriptions for each parameter, including the critical note about never guessing correlationId.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool acts as a payer and performs an action on a case, listing the specific actions. This distinguishes it from sibling tools like nhcx_login or nhcx_workflow, which serve different purposes. The verb+resource is specific enough, though it could be crisper.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for case processing actions but does not explicitly say when to use this tool versus alternatives. It mentions required parameters, which helps, but there are no exclusion criteria or explicit mention of when to prefer sibling tools. The guidance is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nhcx_validate_configA

Validate all environment variables and test connectivity to NHCX APIs. Run this first to confirm your setup is correct.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full transparency burden. It clearly states the actions performed (validating environment variables and testing API connectivity) without implying any hidden side effects. The behavior is unambiguous, though it does not explicitly state whether the operation is read-only or what happens on failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the tool's action. It contains no redundant information and efficiently conveys both purpose and usage timing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema, no annotations), the description adequately covers its purpose and usage. However, it does not specify what output or exit status the user should expect after validation, which would enhance completeness but is not critical for a straightforward validation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and per the guidelines, no parameter description is needed. The description's mention of 'environment variables' and 'API connectivity' indirectly clarifies what is being validated, but since there are no parameters, a baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with specific verbs and resources: 'Validate all environment variables and test connectivity to NHCX APIs.' This distinctly separates it from sibling tools like nhcx_login and nhcx_process_case, and 'Run this first' signals its role as a precursor step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage timing with 'Run this first to confirm your setup is correct.' This gives clear context for when to use the tool, though it does not mention specific alternatives or exclusion cases, which are less necessary given its distinct validation role.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nhcx_workflowA

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Show' implies a read-only operation, and the description details what content is returned (steps, usecase, roles, actions). It does not mention authentication or potential side effects, but for a read-only workflow display, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the verb and resource, densely listing the included details. There is no filler or redundancy, making it exceptionally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description fully specifies what the tool shows (steps, usecase per step, roles, allowed actions). This is sufficient for an agent to understand the tool's behavior fully.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters and an empty schema, the schema coverage is 100% (vacuously). Baseline for 0 params is 4. The description need not explain parameters, and it doesn't.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Show') and resource ('full payer workflow'), and enumerates the included content (steps, usecase per step, roles, allowed actions). This clearly distinguishes it from sibling tools like nhcx_process_case or nhcx_login.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly conveys that this tool is for viewing workflow information, contrasting with the action-oriented siblings. However, it does not explicitly provide when-to-use or when-not-to-use scenarios or name alternatives, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv1.4.0Aug 14, 2026
- First observednhcx_get_user_role
- First observednhcx_login
- First observednhcx_process_case
- First observednhcx_validate_config
- First observednhcx_workflow

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-08-14 11:30 across 5 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: validate config, authenticate, get role/actions, process a case, and view workflow. There is no overlap or ambiguity between them.

Naming Consistency4/5

Most tools follow a consistent verb_noun pattern (validate_config, get_user_role, process_case), though 'login' and 'workflow' deviate slightly. The nhcx_ prefix is applied uniformly, making the set readable and predictable.

Tool Count5/5

Five tools is well-scoped for a payer-focused MCP server. Each tool covers a necessary part of the workflow without redundancy or bloat.

Completeness4/5

The set covers configuration, authentication, role discovery, case actions, and workflow understanding. A potential gap is the lack of a tool to explicitly retrieve full case details before processing, but the included tools appear sufficient for the primary payer workflow.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Medicare Coverage A
io.github.pipeworx-io
MCP server for medicare-coverage
Health & Wellness Government Data Open Data
1
mockmcp A
io.github.K-Cupples
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
Developer Tools Testing & QA Tools
2
modern-treasury A
io.usefulapi
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
Finance Payments & Billing
172
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181

Related MCP Servers

Constructoo MCP Server
CRM Project Management
fgambling
F
license
Not graded
quality
D
maintenance
Mock MCP server for validating Constructoo Copilot data access, exposing read-only tools like counting customer properties, retrieving project status, and fetching appointments.
Updated 4 months ago (2026-05-19 04:52 UTC)
-
mock-llm-mcpofficial
AI & Machine Learning Testing & QA Tools
rebaselabs-framework
A
license
Not graded
quality
D
maintenance
MCP server to mock OpenAI, Anthropic, and Google Gemini responses for testing AI integrations without real API keys or token spend.
Updated 6 months ago (2026-03-18 20:23 UTC)
MIT
bahmni-mcp
Biology & Medicine
lingeswaranTW
F
license
C
quality
C
maintenance
MCP server that exposes the OpenMRS/Bahmni REST API as tools for Claude to interact with Bahmni instances.
Updated 3 months ago (2026-06-28 16:21 UTC)
19
-
Payment-Risk-Exception-AI
Finance Payments & Billing Autonomous Agents
Beste-Oztunc
F
license
Not graded
quality
B
maintenance
MCP server that provides tools for retrieving transaction context and recording AI decisions or creating human reviews for payment risk exceptions. Enables LLM agents to handle exception transactions in a hybrid payment-decisioning workflow.
Updated 2 months ago (2026-08-04 05:01 UTC)
-

nhcx-payer-mcp

Quickstart

MCP Host Configuration

Environment Variables

Required

Optional — Defaults

Optional — URL Overrides

Tools

nhcx_validate_config

nhcx_login

nhcx_get_user_role

nhcx_process_case

nhcx_workflow

nhcx_update_abha_number

Payer Workflow

Testing Workflow Example

Troubleshooting

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mock-llm-mcpofficial

`nhcx_validate_config`

`nhcx_login`

`nhcx_get_user_role`

`nhcx_process_case`

`nhcx_workflow`

`nhcx_update_abha_number`