@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.
| 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="..."
CLEARSALE_BASE_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
- On page load, the merchant calls
create_device_fingerprint_session and embeds ClearSale's browser JS using the returned session_token.
- At checkout, the merchant calls
send_order_for_analysis with the same session_id plus full order, payment, items, and billing/shipping data.
- The response carries a decision:
APROVADO (ship it), REPROVADO (block), or EM_ANALISE (poll get_order_analysis or wait for a webhook).
- Once the order lifecycle completes, call
update_order_status with the final merchant decision — this is required for ongoing model quality.
- If a chargeback arrives later, call
create_chargeback_notification so ClearSale can tune its model.
Run
npx @codespar/mcp-clearsale
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