CommerceGate MCP

CommerceGate MCP gives operations agents a tenant-bound Shadow Mode preflight for price, inventory, order, fulfillment, promotion, refund, and return actions, plus enforced Dynamics 365 transaction authorization, signed decision evidence, and reports.

The server runs locally over STDIO and calls the Decionis API. commercegate_evaluate_action records a Shadow Mode policy evaluation; it does not execute the proposed action in a marketplace or ERP. commercegate_validate_erp_transaction performs enforced binary policy and agent-budget authorization for a complete Dynamics 365 transaction, but it does not post, release, modify, or otherwise write that transaction. Refund, oversell, and other connector execution paths remain separate and are available only when the connected platform exposes the required API, the merchant grants its required scope, and the Commerce Gate connector implements and enables that path.

Package: @decionis/commerce

What operators use it for

• “Would repricing this SKU to $89 still clear our margin floor?” → PRICE_CHANGE
• “Would reducing this location from 47 to 7 units breach the inventory floor?” → INVENTORY_MUTATION
• “Would accepting this discounted order clear its supplied economics?” → ORDER_ACCEPTANCE
• “May this order be acknowledged, shipped, cancelled, or held?” → FULFILLMENT_ACTION
• “Does this proposed promotion need review?” → PROMOTION_CHANGE
• “Does this refund request fit the active policy?” → REFUND_REQUEST
• “May this return or RMA be authorized?” → RETURN_AUTHORIZATION
• “Does this complete Dynamics 365 transaction clear policy and the agent budget?” → commercegate_validate_erp_transaction
• “What would Shadow Mode have held this month, and why?” → the Shadow Report tools
• “Finance needs the signed evidence for this dossier.” → the dossier and proof-packet tools

Outcomes map to the operator vocabulary used across Commerce Gate: APPROVE → PROCEED, REVIEW → HOLD, ESCALATE → HOLD, and REJECT → BLOCK. Stop on HOLD, BLOCK, an error, or an ambiguous response. PROCEED is a policy result, not consent to execute.

Install

CommerceGate requires Node.js 20 or later. Start the pinned public package with:

npx -y @decionis/commerce@0.1.3

The process starts without credentials so an MCP client can discover its capabilities. The ERP guard requires DECIONIS_API_KEY; Protocol evaluation and evidence tools require both DECIONIS_API_KEY and DECIONIS_ORG_ID. Store DECIONIS_API_KEY in the MCP client’s secret or environment manager; never place it in command arguments, source control, prompts, or logs. DECIONIS_API_BASE is optional and defaults to https://api.decionis.com.

For a capability-only startup, omit the credential variables and call commercegate_describe_capabilities. Every authenticated call fails closed until its required configuration is available.

Codex client configuration

Forward the three named variables from the environment that launches Codex:

[mcp_servers.commercegate]
command = "npx"
args = ["-y", "@decionis/commerce@0.1.3"]
env_vars = ["DECIONIS_API_KEY", "DECIONIS_ORG_ID", "DECIONIS_API_BASE"]
enabled = true
required = false
startup_timeout_sec = 20
tool_timeout_sec = 45
default_tools_approval_mode = "writes"
enabled_tools = [
  "commercegate_describe_capabilities",
  "commercegate_validate_erp_transaction",
  "commercegate_evaluate_action",
  "commercegate_get_dossier",
  "commercegate_get_proof_packet",
  "commercegate_list_shadow_reports",
  "commercegate_summarize_shadow_reports",
]

Tools

Action contract

Every action includes a stable actor, a platform, and a bounded idempotency_key. The payload is selected by action_type:

Order acceptance and price change have native CommerceGate margin mappings. The other five action types are generic Protocol Shadow evaluations: the server validates and normalizes their shape, but the result is only as complete as the active tenant policy and the submitted facts. A verdict says whether the action clears policy, not whether the platform's connector can carry it out.

The ERP guard accepts a bounded erp_region and the complete canonical D365 request: transaction_id, erp_type, tenant_id, timestamp, agent_id, currency, and 1–200 line records. It sends the configured API key as X-Decionis-API-Key and the region as X-ERP-Region. An ALLOW response means the exact request cleared enforced policy and its idempotent agent-budget authorization; it is not user consent and the MCP still performs no ERP write. The guard returns a reason code and message but does not promise a retrievable Decision Dossier or proof packet for that call.

The Shadow Report tools accept an optional days window from 1–365 and limit from 1–100. Both read the canonical /v1/protocol/shadow-reports document; the list tool presents operational rows while the summary tool presents its aggregate view.

Minimal end-to-end example

With DECIONIS_API_KEY and DECIONIS_ORG_ID set in the MCP process environment, call commercegate_evaluate_action with:

{
  "action": {
    "action_type": "REFUND_REQUEST",
    "actor": { "type": "AGENT", "id": "support-agent" },
    "platform": "walmart-marketplace",
    "idempotency_key": "order:123:refund:line-1:v1",
    "payload": {
      "order_id": "123",
      "amount": 180,
      "currency": "USD",
      "reason_code": "CustomerReturn"
    }
  },
  "policy_version": "commerce-2026-09"
}

The response contains the Protocol evaluation, the normalized CommerceGate disposition, and explicit agent guidance. It also states that no downstream action was executed. A separate Walmart connector can submit a product-line refund only for an eligible shipped or delivered line and only up to its remaining refundable product amount; this MCP call neither checks that live order state nor submits the refund.

Safety contract

• commercegate_evaluate_action is hard-locked to SHADOW. It may create an evaluation and Decision Dossier, but it never executes the proposed action.
• commercegate_validate_erp_transaction is an enforced ALLOW/BLOCK decision and can reserve agent budget idempotently. It never writes the transaction to Dynamics 365.
• APPROVE is evidence, not user consent and not permission to mutate a marketplace.
• REJECT means stop. REVIEW or ESCALATE means hold and involve an authorized human.
• Protocol calls are bound to DECIONIS_ORG_ID; tools never accept an organization override. The ERP guard instead authenticates the submitted tenant_id with the configured API key.
• Tenant failures and unknown outcomes fail closed to HOLD. The process never silently routes around CommerceGate.
• API credentials are never returned. Safe errors omit configured organization values and upstream response bodies.
• Connector execution is conditional and separate. Do not translate an unavailable action into a different action type.

Connector boundary

Refund and oversell controls are connector-gated. Depending on the connector, Commerce Gate may return a decision, withhold order release, or submit an explicitly confirmed action. A connected status alone is not enough: execution requires the marketplace API, merchant-granted scope, implemented and enabled connector path, and explicit execution authority. If any condition is missing, the capability remains evaluation-only or unavailable.

Current shipped examples:

• Walmart supports order reads, policy-evaluated acknowledgment, and operator-confirmed ship, cancel, and product-line refund paths. Refunds are limited to eligible shipped or delivered lines and the remaining refundable product amount. None of those writes are exposed through this MCP.
• Shopify Functions enforce configured margin rules at checkout, in discount handling, and in payment-method selection. A separate Shopify Flow action performs a post-order Shopify inventory-floor check and records a decision; it does not hold, cancel, modify, or refund the order, and it does not currently compare another marketplace’s inventory.

Outcome semantics

The ERP guard uses a separate binary vocabulary: ALLOW maps to PROCEED for the exact validated transaction, while BLOCK means stop. ALLOW remains authorization evidence rather than user consent, and no ERP write occurs inside the MCP.

Configuration

The API base must use HTTPS. HTTP is accepted only for loopback development.

Develop from source

pnpm --filter @decionis/commerce typecheck
pnpm --filter @decionis/commerce test
pnpm --filter @decionis/commerce build
pnpm --silent --filter @decionis/commerce mcp

Privacy Policy

CommerceGate MCP runs on your machine and talks to one service: the Decionis API at https://api.decionis.com (or the origin you set in DECIONIS_API_BASE). It has no telemetry, no analytics, no crash reporting and no other network destination. The full Decionis privacy policy is at https://decionis.com/privacy; this section describes what this server specifically does.

What it collects. Nothing on its own. Everything it sends is what the agent passes into a tool call: the commerce facts being checked (SKU, current and new price or quantity, landed cost, order amounts, discount, refund amount and reason, promotion facts, actor type and a non-secret actor identifier, platform, idempotency key), a dossier UUID for evidence reads, and a report window for Shadow reports. It never reads files, browser data, clipboard or anything else on the machine.

Where it goes and why. Tool inputs are sent over HTTPS to the Decionis API to evaluate them against your organization's policy and to read evidence you already own. The request carries your DECIONIS_API_KEY as a bearer token, your DECIONIS_ORG_ID to scope the call to your organization, and a user-agent naming this package and version. Credentials are read from the process environment, never written to disk or logs by this server, and never returned in any tool result.

What is stored. Decionis stores the evaluation as a signed Decision Dossier in your organization's workspace so it can be verified later; that is the product. Retention follows your Decionis plan and the Decionis privacy policy. This server itself stores nothing: no cache, no log file, no local database. On a failed request it writes one fixed line to stderr with no request contents.

Third parties. None. Decionis does not sell or share tool inputs, and this server contacts no third-party service. Your MCP client (Claude Desktop, Codex, VS Code or another host) may log tool calls under its own policy.

Personal data. Commerce facts can include order identifiers and, if you pass them, customer-related amounts. Send only what the policy check needs; the server accepts a bounded, typed action and rejects unknown fields.

Your controls. Remove DECIONIS_API_KEY and DECIONIS_ORG_ID and the server can only describe its capabilities. Uninstall the package or extension to stop all processing. To access, correct or delete dossiers held by Decionis, or to ask anything about this policy, write to mailto:commerce@decionis.com; security reports go to mailto:security@decionis.com (see https://commerce.decionis.com/.well-known/security.txt).

Support and license

• Support: Contact Decionis
• License: Apache-2.0