Model Context Protocol (MCP)

The IIMMPACT Model Context Protocol (MCP) server lets compatible AI hosts inspect reseller data and perform approved operations through the IIMMPACT API. It exposes the same reseller-scoped capabilities as the API; MCP does not grant additional access or bypass product entitlements.

Staging first

Connect to staging and validate every read, preview, approval, and error path before using production. Writes can change account configuration, open support requests, issue refunds, or create financial transactions.

Endpoints

Environment	Streamable HTTP endpoint
Staging	https://staging.iimmpact.com/mcp
Production	https://api.iimmpact.com/mcp

The MCP endpoint accepts server-to-server POST /mcp requests. Do not call it directly from browser code: an API key and HMAC secret must never be shipped to, stored in, or exposed by a browser.

Architecture

The remote server uses stateless MCP Streamable HTTP. Each JSON-RPC request is self-contained and authenticated independently; the service does not require a sticky session or retain an MCP session between requests.

The local @iimmpact-sdn-bhd/mcp signer bridges standard MCP stdio hosts to Streamable HTTP. It creates a fresh timestamp and nonce and signs the exact JSON-RPC body for every request. Your API key and HMAC secret remain under your control; the HMAC secret is used locally and is never sent to the MCP server as a credential value.

The bridge does not provide stateful MCP sessions, resumable streams, server-to-client requests, or JSON-RPC batch input. It serializes requests and supports JSON responses, SSE data: frames, and notification 202 responses.

Configure the local signer

Create an API key and HMAC secret in the IIMMPACT Dashboard under Developer > API Keys. API key and HMAC authentication remains customer-side: you are responsible for securely storing the credentials, controlling which host process receives them, and rotating them when needed.

The signer is published on npm as @iimmpact-sdn-bhd/mcp. Configure your MCP host to run the published package through npx:

Use environment variables rather than command-line credential arguments:

{
  "mcpServers": {
    "iimmpact-staging": {
      "command": "npx",
      "args": ["-y", "@iimmpact-sdn-bhd/mcp@latest"],
      "env": {
        "IIMMPACT_API_KEY": "your-staging-api-key",
        "IIMMPACT_HMAC_SECRET": "your-base64-encoded-hmac-secret",
        "IIMMPACT_MCP_URL": "https://staging.iimmpact.com/mcp",
        "IIMMPACT_MCP_TIMEOUT_MS": "120000"
      }
    }
  }
}

Variable	Required	Description
IIMMPACT_API_KEY	Yes	API key associated with the reseller account.
IIMMPACT_HMAC_SECRET	Yes	Base64-encoded HMAC secret shown when the key is created or rotated.
IIMMPACT_MCP_URL	Yes	Staging or production MCP endpoint shown above.
IIMMPACT_MCP_TIMEOUT_MS	No	Request timeout from 35,000 to 300,000 ms; defaults to 120,000 ms.
IIMMPACT_MCP_PROTOCOL_VERSION	No	Pins the MCP protocol version when a host requires it from the first request.

Keep staging and production credentials in separate secret stores and host configurations. Never place credentials in source control, prompts, tool arguments, logs, screenshots, shell history, or browser storage.

Available tools

Tool availability is scoped to the authenticated reseller and the environment's enabled capabilities.

Read tools (15)

Tool	Purpose
get_balance	Get the reseller's current balance.
list_transactions	List reseller transactions with bounded filters and pagination.
get_transaction	Get one reseller transaction by transaction ID.
get_balance_statement	Get a balance statement for a date or date range.
get_catalog	Get catalog entries available to the reseller.
get_options	Get dynamic options for a product field.
get_subproducts	Get legacy subproducts for a product and account context.
get_product_list	List legacy products available to the reseller.
get_products	Search legacy reseller products.
get_network_status	Get current service availability.
get_bill_presentment	Perform a bill inquiry before payment.
list_jompay_billers	List or search available JomPAY billers.
get_jompay_biller_directory	Search the enriched JomPAY biller directory.
get_callback	Get transaction callback configuration.
get_low_balance	Get the low-balance notification threshold.

Write tools (6)

Tool	Purpose
set_callback	Set the callback URL and HTTP method.
delete_callback	Delete matching callback configuration.
set_low_balance	Set the low-balance notification threshold.
check_transaction	Request a transaction status check.
void_transaction	Request a transaction refund.
topup	Submit a financial topup or bill-payment transaction.

Write tools may be disabled for an environment even when read tools are available. JomPAY tools and JomPAY operations require the authenticated reseller to have JomPAY entitlement; MCP does not add that entitlement.

Human approval for writes

Every write uses a mandatory preview-to-confirmation flow:

1. Preview — Call the write tool without confirm: true. The server returns executed: false, the normalized operation details, and a short-lived confirmationToken. Nothing is changed.
2. Human approval — Show the exact preview to a human. Do not infer approval, hide material fields, or approve automatically.
3. Execute once — After approval, call the same tool with the same operation input, confirm: true, and the returned confirmationToken.

The token is bound to the tool, exact input, reseller, and API key. It expires and can be consumed only once. If the input changes, the token expires, or confirmation storage is unavailable, preview the operation again and request fresh approval.

Topup reference ID and idempotency

For topup, the client creates the refid, which acts as the idempotency key within the authenticated reseller:

• For a new topup, generate a new unique refid before preview. UUID v4 is recommended.
• Keep the complete topup input and refid unchanged through preview and confirmation.
• For a retry or status check, resend the same valid topup input with the same refid.
• When a transaction already exists for that reseller and refid, IIMMPACT returns the existing transaction and its current status instead of creating another topup.
• Use a new refid only when intentionally creating a new topup.

Financial retries

If a confirmed topup has an uncertain transport outcome, check transaction status or retry with the same refid. Never create a new refid for that attempt, because doing so can create a duplicate financial transaction.

For check_transaction and void_transaction, the user must explicitly provide at least one valid notification email address. An agent must not invent, guess, or reuse an example address.