@codespar/mcp-clearsale

MCP server for ClearSale — Brazilian fraud prevention.

ClearSale pioneered fraud analytics in Brazil (founded 2001, São Paulo) and remains the default antifraud layer for most major BR ecommerce. This is the first entry in the CodeSpar fraud category — no other server in the catalog does fraud scoring. Future entries (Konduto, Legiti, Sift, Cybersource) will follow the same analyze → decide → feedback shape.

Tools (18)

| Tool | Purpose | |---|---| | send_order_for_analysis | Submit an order to ClearSale for fraud analysis. | | get_order_analysis | Retrieve the current analysis state of an order previously sent to ClearSale. | | update_order_status | Notify ClearSale of the merchant's final decision on an order (APROVADO / CANCELADO / DEVOLVIDO). | | list_orders | List orders submitted to ClearSale with optional filters. | | create_chargeback_notification | Report a confirmed chargeback back to ClearSale. | | get_order_score | Fetch only the fraud score (numeric 0-100) for an order. | | create_device_fingerprint_session | Start a device fingerprint session. | | get_device_fingerprint | Retrieve captured device characteristics for a fingerprint session (OS, browser, timezone, canvas/WebGL has... | | resolve_manual_review | Manually resolve an order currently in EM_ANALISE by approving or declining it. | | get_score_by_document | Look up the risk score and historical signals associated with a Brazilian document (CPF or CNPJ). | | get_score_by_contact | Look up the risk score for a contact identifier (email or phone). | | validate_document | KYC: validate a CPF or CNPJ against Receita Federal. | | validate_address | KYC: validate a Brazilian postal address against the Correios database. | | track_behavior_event | Log a behavior signal (page view, login, signup, custom event) tied to a fingerprint session. | | issue_challenge | Issue an authentication challenge (OTP via SMS/email or KBA question) to a buyer. | | validate_challenge_response | Verify a buyer's response to a challenge issued via issue_challenge. | | create_case | Open a fraud investigation case (e.g. | | update_case | Update an existing fraud investigation case — change status, add notes, reassign, or attach more orders. |

Install

npm install @codespar/mcp-clearsale@alpha

Environment

CLEARSALE_API_KEY="..."    # Bearer token issued by ClearSale
CLEARSALE_BASE_URL="..."   # Optional. Defaults to https://api.clearsale.com.br. Override per contract-issued staging URL.

Authentication

Server-side Bearer token:

Authorization: Bearer <CLEARSALE_API_KEY>

ClearSale issues the token via the developer portal or through your commercial contract. There is no public sandbox — staging URLs are provisioned per contract; override CLEARSALE_BASE_URL to point at it.

Typical flow

1. On page load, the merchant calls create_device_fingerprint_session and embeds ClearSale's browser JS using the returned session_token.
2. At checkout, the merchant calls send_order_for_analysis with the same session_id plus full order, payment, items, and billing/shipping data.
3. The response carries a decision: APROVADO (ship it), REPROVADO (block), or EM_ANALISE (poll get_order_analysis or wait for a webhook).
4. Once the order lifecycle completes, call update_order_status with the final merchant decision — this is required for ongoing model quality.
5. If a chargeback arrives later, call create_chargeback_notification so ClearSale can tune its model.

Run

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

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

Category

fraud — first server in this CodeSpar category. 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