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 (19)

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 the dynamic product catalog, optionally including products that are turned off.
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.
list_catalog_groups	List catalog groups with order, visibility, and whether each is custom.
list_catalog_categories	List catalog categories with their group, order, and visibility.
list_catalog_options	List a product's options (denominations, plans, packages) with visibility, order, price, and cost.
get_catalog_webhook	Get the catalog webhook URL and status. The secret is never returned.

Write tools (17)

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.
upsert_catalog_groups	Create custom groups, or rename, reorder, show, or hide groups.
upsert_catalog_categories	Create custom categories, or rename, reorder, show, hide, or move categories between groups.
delete_catalog_group	Delete a custom group or revert a customized base group, including your categories and product assignments in it.
delete_catalog_category	Delete a custom category or revert a customized base category, including your product assignments in it.
update_catalog_products	Turn products on or off, rename them, edit notes, move or reorder them, set price adjustments, or narrow amount ranges.
update_catalog_options	Offer or withdraw individual denominations, plans, or packages, or reorder them.
reset_catalog_products	Restore products to IIMMPACT defaults, removing all of their customizations.
set_catalog_webhook	Register or replace the catalog webhook URL. Returns a new signing secret once.
set_catalog_webhook_enabled	Pause or resume catalog webhook delivery.
rotate_catalog_webhook_secret	Replace the catalog webhook signing secret. Returns the new secret once.
delete_catalog_webhook	Remove the catalog webhook.

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.

Catalog management

The catalog tools manage the same customizations as Products > Catalog in the IIMMPACT Dashboard; see Manage Your Catalog. Changes take effect immediately and trigger catalog webhooks.

• Partial updates — Fields you omit keep their current values. Each item must change at least one field, and unknown or misspelled argument names are rejected rather than ignored. For update_catalog_products, omit priceAdjustment to keep the current adjustment, or send {"type": "none"} to remove it. Omit amountRange to keep the current range, or send {} to restore the product's default range. Names, groupCode, and categoryCode cannot be blank, and a group or category you assign something to must already exist.
• Price adjustments — fixed adds an MYR amount to the price, and a negative value gives a discount. percentage multiplies the price, so 1.03 adds 3% and 0.98 takes off 2%; it must be greater than 0 and at most 2. Values allow up to 4 decimal places. See Pricing.
• Batches — The group, category, product, option, and reset tools accept 1–50 items and need one approval for the whole list. Items are applied in order, and each item sees the changes made by earlier items. The tool stops at the first item that fails. If the first item is rejected, for example by validation, the call fails and nothing is changed. If a later item fails, earlier items stay applied, and the result lists the applied items, the failed item and its error, and the items that were not attempted. If an item fails unexpectedly, its outcome is uncertain: check the current state before retrying it.
• Cascading deletes — Deleting a category also removes all customizations, including price adjustments and option settings, of products you assigned to that category. Deleting a group does the same for your customized categories in that group. Products that only inherit a category from the IIMMPACT catalog keep their customizations. Base groups and categories cannot be removed, only reverted to their defaults.
• Webhook URLs — set_callback and set_catalog_webhook accept only absolute http or https URLs without user credentials, so the host shown for approval is the host that receives deliveries. Production catalog webhooks require https.
• Field names — Catalog tool arguments are camelCase, such as groupCode and priceAdjustment. Previews echo those arguments with snake_case names, such as group_code and price_adjustment; send the original camelCase arguments when you confirm. Read results and executed write results use the same snake_case names as the catalog REST API, such as product_group_code, display_order, and is_custom.
• Webhook secrets — set_catalog_webhook and rotate_catalog_webhook_secret return the signing secret once. Store it in your secret manager immediately; it cannot be retrieved later.

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.

If a confirmed write fails unexpectedly, its outcome is uncertain: check the current state before retrying.

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.