ClearSale

v0.2.0-alpha.1API Keyalpha

Brazilian fraud prevention pioneer (founded 2001). Order risk scoring, device fingerprinting, chargeback feedback. Alpha release on npm — endpoints pending validation against contract-gated ClearSale developer portal.

18 tools2 env vars🇧🇷 Brazilalpha — pending validation

Install

terminal

$ npm install @codespar/mcp-clearsale@alpha

Quickstart

Add this entry to your claude_desktop_config.json (or any MCP-compatible client config).

claude_desktop_config.json

{
  "mcpServers": {
    "clearsale": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-clearsale@alpha"
      ],
      "env": {
        "CLEARSALE_API_KEY": "<your_clearsale_api_key>"
      }
    }
  }
}

After restart, your agent can call any of the 18 tools below — try send_order_for_analysis first.

Environment variables · 2

Required to authenticate the server. Stored encrypted when using CodeSpar managed hosting.

CLEARSALE_API_KEY

requiredsecret

ClearSale API key / bearer token used in the Authorization header

CLEARSALE_BASE_URL

optional

ClearSale API base URL. Defaults to https://api.clearsale.com.br (prod). Override per contract-issued staging URL.

Available tools · 18

Each tool is independent — your agent loads only what it needs to reduce context and response time.

WRITEsend_order_for_analysis

Submit an order to ClearSale for fraud analysis. Returns a score (0-100) and a decision (APROVADO / REPROVADO / EM_ANALISE). Include as much signal as possible — billing + shipping, IP, device, items, and payment — to improve the decision.

READget_order_analysis

Retrieve the current analysis state of an order previously sent to ClearSale. Useful when the initial response was EM_ANALISE and the decision is made asynchronously.

WRITEupdate_order_status

Notify ClearSale of the merchant's final decision on an order (APROVADO / CANCELADO / DEVOLVIDO). This feeds the ML model and is required for accurate future decisions on the same buyer.

READlist_orders

List orders submitted to ClearSale with optional filters. Use for dashboards, reconciliation, and reviewing pending manual decisions.

WRITEcreate_chargeback_notification

Report a confirmed chargeback back to ClearSale. Critical for model tuning: unreported chargebacks degrade future decision quality for similar buyers.

READget_order_score

Fetch only the fraud score (numeric 0-100) for an order. Lighter than get_order_analysis when the full decision envelope isn't needed.

WRITEcreate_device_fingerprint_session

Start a device fingerprint session. Returns a session_token the client embeds via ClearSale's browser JS SDK to capture device characteristics. Pass the same session_id into send_order_for_analysis to link the device to the order.

READget_device_fingerprint

Retrieve captured device characteristics for a fingerprint session (OS, browser, timezone, canvas/WebGL hash, suspected emulator, etc).

Compatible frameworks

MCP is a protocol — any framework that speaks it can mount this server.

Claude Agent SDKAnthropic

OpenAI AgentsOpenAI

Vercel AI SDKVercel

LangChainLangChain

LlamaIndexLlamaIndex

CrewAICrewAI

MastraMastra

Any MCP clientProtocol

Frequently asked questions

All credentials are encrypted at rest in an isolated vault scoped per organization. OAuth2 tokens are automatically refreshed before expiry. Your agent code never sees raw secrets — it receives scoped, short-lived session tokens.