@codespar/mcp-konduto

@codespar/mcp-konduto

MCP server for Konduto — Brazilian fraud prevention, API-first.

Second entry in the CodeSpar fraud category after @codespar/mcp-clearsale. Konduto sits alongside ClearSale as one of the two default antifraud layers BR merchants evaluate, and the two are often deployed in parallel for score comparison or failover.

Positioning vs. ClearSale

	ClearSale	Konduto
Founded	2001 (São Paulo)	2014 (São Paulo)
Strength	Larger chargeback history database	Behavioral device intelligence
Shape	ML scoring + manual review services	API-first, tighter surface, dev-oriented
Typical pairing	Default for large BR retail	Default for digital-native BR ecommerce

Merchants commonly run both in parallel: Konduto for the fast behavioral signal, ClearSale for the long-tail chargeback history. When one flags review and the other flags approved, the merchant routes the order to manual inspection.

Tools (18)

Tool	Purpose
send_order_for_analysis	Submit an order to Konduto for fraud analysis.
get_order	Retrieve the current analysis state of an order.
update_order_status	Notify Konduto of the merchant's final status for an order.
report_chargeback	Report a confirmed chargeback for an order.
report_order_approved	Report that an order was ultimately approved by the merchant.
report_order_declined	Report that an order was ultimately declined by the merchant.
add_to_blocklist	Add a value to the Konduto blocklist.
query_blocklist	Check whether a value is currently on the Konduto blocklist.
update_blocklist_entry	Update an existing blocklist entry — typically used to extend or shorten the expiration window (expires_at)...
remove_from_blocklist	Remove a value from the Konduto blocklist.
add_to_allowlist	Add a value to the Konduto allowlist (trusted).
query_allowlist	Check whether a value is currently on the Konduto allowlist.
update_allowlist_entry	Update an existing allowlist entry — typically to extend or shorten the expiration window.
remove_from_allowlist	Remove a value from the Konduto allowlist.
add_to_reviewlist	Add a value to the Konduto reviewlist.
query_reviewlist	Check whether a value is currently on the Konduto reviewlist.
update_reviewlist_entry	Update an existing reviewlist entry — typically to extend or shorten the expiration window without removing...
remove_from_reviewlist	Remove a value from the Konduto reviewlist.

Install

npm install @codespar/mcp-konduto@alpha

Environment

KONDUTO_API_KEY="T00000..."          # private key; required
KONDUTO_BASE_URL="..."               # optional; defaults to https://api.konduto.com/v1

Authentication

HTTP Basic. The API key is the username; password is empty:

Authorization: Basic base64(KONDUTO_API_KEY + ":")

The server handles the base64 encoding — pass the raw key in KONDUTO_API_KEY.

Typical flow

• Embed Konduto's browser JS SDK on the merchant checkout page. It captures a visitor id (behavioral + device signals).
• At order submit, call send_order_for_analysis with the full order payload and the visitor id.
• Act on the response: approved ships it, declined blocks it, review holds for manual inspection or a second signal from ClearSale.
• Once the order lifecycle completes, call update_order_status with approved / canceled / fraud — this feeds Konduto's model.
• When a chargeback is confirmed, call update_order_status with status fraud. This is Konduto's primary ML feedback channel (there is no separate /chargebacks endpoint in the public docs).
• Use add_to_blocklist to permanently block specific emails / IPs / card BIN+last4 pairs observed in confirmed fraud.

Alpha note

This package is shipped as 0.1.0-alpha.1. Scope vs. the original brief:

• Verified against docs.konduto.com:

  • POST /orders (send_order_for_analysis)
  • POST/GET/DELETE /blacklist/{type} (blocklist family)
  • /whitelist/{type} (allowlist) and /greylist/{type} (reviewlist), indexed under "APIs de Blocklist, Allowlist e Reviewlist"

• Standard REST pattern, not separately indexed in the public reference (used by Konduto's official client libraries):

  • GET /orders/{id} (get_order)
  • PUT /orders/{id} (update_order_status)

• Dropped — not documented publicly:

  • POST /disputes — no dispute submission endpoint on docs.konduto.com
  • POST /cards/analyze — no card-only pre-check endpoint documented
  • GET /visitors/{visitor_id} — visitor ids are referenced on the order (visitor field) but no public retrieval endpoint exists

Chargeback feedback is folded into update_order_status with status: fraud, which is Konduto's documented feedback channel.

Promote to 0.2.0 once the dropped endpoints are confirmed (via private docs or direct API response), or once Konduto publishes a broader public reference.

Run

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-konduto

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-konduto

Category

fraud — second server in this CodeSpar category after ClearSale. Fraud servers share a common shape (analyze → decide → feedback) distinct from payments, which makes cross-provider swaps (ClearSale ↔ Konduto ↔ Legiti) more straightforward than cross-acquirer swaps.

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT