# io.github.codespar/mcp-santander (npm · @codespar/mcp-santander)

MCP server for Santander Brasil — Pix, Cobrança (boleto), Arrecadação, Extrato (OAuth2 + mTLS)

- Trust score: 69/100 (medium)
- Change this week: +23
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-04

## Components

- npm · `@codespar/mcp-santander`: 69/100 (this document), [markdown](https://verifymcp.io/servers/codespar-mcp-santander/codespar-mcp-santander.md), [page](https://verifymcp.io/servers/codespar-mcp-santander/codespar-mcp-santander)

## Channel facts

- Registry: `npm`
- Package: `@codespar/mcp-santander`
- Version: `0.2.0-alpha.3`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-04.

- **Supply Chain Security**: 83/100
  - No malware found by supply-chain analysis.
  - CVE check failed: a known medium-severity CVE affects hono 4.12.33, reached via @modelcontextprotocol/sdk > hono. A fixed version is available.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 42 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 76/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2540 tokens (~110/item across 23 items; 23 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 30/100
  - Stability observed for 9 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add codespar-mcp-santander -- npx -y @codespar/mcp-santander
```

### Codex

```bash
codex mcp add codespar-mcp-santander -- npx -y @codespar/mcp-santander
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codespar-mcp-santander": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@codespar/mcp-santander"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add codespar-mcp-santander --command npx --arg -y --arg @codespar/mcp-santander
```

### Hermes

```yaml
mcp_servers:
  codespar-mcp-santander:
    command: "npx"
    args: ["-y", "@codespar/mcp-santander"]
```

### Other

```json
{
  "mcpServers": {
    "codespar-mcp-santander": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-santander"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-04 (score 69, +4)

- [security regression] CVE-2026-69207 affects this package: medium
- [security regression] Known CVEs: partial → fail
- [functional improvement] Stability: unverified → 0.30

### 2026-08-02 (score 65, +39)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Capabilities: pass → unverified
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional] Licence: MIT

### 2026-08-01 (score 26, +5)

- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] MCP protocol: unverified → pass

### 2026-07-31 (score 21, −25)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-27 (score 46)

First indexed and scored.

## MCP tools (23)

### `get_oauth_token` (~43 tokens)

Mint or return a cached OAuth2 client_credentials bearer token for the Santander Developer Portal. Exposed so agents can inspect token freshness; normal tool calls obtain tokens implicitly.

### `send_pix` (~136 tokens)

Initiate an outbound Pix payment from the merchant's Santander account. Amount in BRL major units (e.g. '10.50').

Input parameters:

- `amount` (string, required): Amount in BRL major units with two decimals, e.g. '10.50'
- `description` (string): Free-text description shown on the statement (max 140 chars)
- `idempotency_key` (string, required): Merchant-side idempotency key (UUID recommended)
- `payee` (object, required): Payee identification — either a DICT key or explicit bank account
- `payer_account` (string, required): Merchant account to debit (agência-conta)

### `create_pix_qr` (~127 tokens)

Create a dynamic Pix charge with QR code (cob). Returns the txid, copy-paste EMV payload, and location URL.

Input parameters:

- `additional_info` (array): Optional free-text key/value info shown to the payer
- `amount` (string, required): Amount in BRL major units, e.g. '99.90'
- `description` (string): Payer-visible description
- `expires_in` (number): QR lifetime in seconds (default 3600)
- `payer` (object): Payer identification (required by BCB for cobv / common for cob)

### `get_pix` (~51 tokens)

Retrieve a Pix transaction by its BCB endToEndId (E<ispb><yyyymmddhhmm><sequence>).

Input parameters:

- `end_to_end_id` (string, required): BCB endToEndId

### `resolve_dict_key` (~92 tokens)

Resolve a DICT key (CPF, CNPJ, email, phone, EVP) to the owner's account data before sending a Pix. Subject to BCB rate limits per consenting payer.

Input parameters:

- `key` (string, required): DICT key — CPF, CNPJ, email, phone (+55...), or EVP UUID
- `payer_document` (string): Merchant / end-payer CPF/CNPJ for BCB audit logging

### `refund_pix` (~109 tokens)

Refund (devolução) a previously received Pix. Must reference the original endToEndId and a merchant-side refund id.

Input parameters:

- `amount` (string): Refund amount in BRL major units. Omit for full refund.
- `end_to_end_id` (string, required): Original Pix endToEndId to refund
- `reason` (string): Free-text reason (stored by BCB for audit)
- `refund_id` (string, required): Merchant-side refund identifier (alphanumeric up to 35 chars)

### `create_boleto` (~209 tokens)

Issue a boleto via Santander Cobrança (collection_bill_management v2). Requires a pre-provisioned workspace_id that binds the covenant and webhook config. Returns bill_id, linha_digitável, barcode, and PDF URL.

Input parameters:

- `amount` (string, required): Amount in BRL major units, e.g. '150.00'
- `due_date` (string, required): Due date ISO-8601 (YYYY-MM-DD)
- `fine` (object): Multa (fine after due date): { percentage?, amount?, days_after_due? }
- `instructions` (array): Free-text instructions printed on the boleto
- `interest` (object): Juros (daily interest after due date): { percentage?, amount? }
- `our_number` (string): Nosso_numero. Omit to have Santander assign one.
- `payer` (object, required): Payer (sacado) data
- `workspace_id` (string, required): Santander workspace_id (defines convênio + webhook). Provision once via the Developer Portal.

### `get_boleto` (~59 tokens)

Retrieve a boleto by its Santander bill_id (SONDA query via collection_bill_management v2).

Input parameters:

- `bill_id` (string, required): Santander bill_id / bank_slip identifier
- `workspace_id` (string, required): Santander workspace_id that owns the boleto

### `cancel_boleto` (~64 tokens)

Cancel (baixa) an outstanding boleto before payment.

Input parameters:

- `bill_id` (string, required): Santander bill_id / bank_slip identifier
- `reason` (string): Cancellation reason code or free text
- `workspace_id` (string, required): Santander workspace_id that owns the boleto

### `get_statement` (~97 tokens)

Retrieve account statement transactions for a given period. Paginated.

Input parameters:

- `account` (string, required): Agência-conta identifier of the merchant account
- `from` (string, required): Start date ISO-8601 (YYYY-MM-DD)
- `page` (number): Page number (1-indexed)
- `page_size` (number): Items per page (default 50)
- `to` (string, required): End date ISO-8601 (YYYY-MM-DD)

### `create_pix_cobv` (~210 tokens)

Create a Pix charge with due date (cobv — cobrança com vencimento). Used for boleto-replacement flows: the payer sees a Pix QR with a due date, fine, and interest. Requires payer identification.

Input parameters:

- `amount` (string, required): Original amount in BRL major units, e.g. '250.00'
- `description` (string): Payer-visible description
- `discount` (object): Desconto: { modalidade, descontoDataFixa }
- `due_date` (string, required): Due date ISO-8601 (YYYY-MM-DD)
- `fine` (object): Multa: { modalidade, valorPerc }
- `interest` (object): Juros: { modalidade, valorPerc }
- `payer` (object, required): Payer identification (mandatory for cobv)
- `txid` (string, required): 26-35 char alphanumeric txid chosen by the merchant
- `validity_after_due` (number): Days the QR remains payable after due_date (default 30)

### `get_pix_cob` (~50 tokens)

Retrieve a Pix immediate charge (cob) by its txid. Returns status, EMV payload, and location.

Input parameters:

- `txid` (string, required): Merchant-chosen txid of the cob

### `list_pix_cob` (~135 tokens)

List Pix immediate charges (cob) created in a given period. Paginated; filter by status optional.

Input parameters:

- `from` (string, required): Start timestamp ISO-8601 (inicio)
- `page` (number): Page number (paginacao.paginaAtual)
- `page_size` (number): Items per page (paginacao.itensPorPagina)
- `status` (string): Filter by cob status: ATIVA | CONCLUIDA | REMOVIDA_PELO_USUARIO_RECEBEDOR | REMOVIDA_PELO_PSP
- `to` (string, required): End timestamp ISO-8601 (fim)

### `update_pix_cob` (~124 tokens)

Update (PATCH) an existing Pix immediate charge. Typical uses: change status to REMOVIDA_PELO_USUARIO_RECEBEDOR, adjust amount or payer info on an ATIVA charge.

Input parameters:

- `amount` (string): New original amount (if editable)
- `description` (string): Updated payer-visible description
- `payer` (object): Updated payer data (document, name)
- `status` (string): New status, e.g. REMOVIDA_PELO_USUARIO_RECEBEDOR
- `txid` (string, required): txid of the cob to update

### `list_pix_received` (~135 tokens)

List received Pix (Pix recebidos) in a given period. Used for reconciliation of inbound payments, including those without an associated cob.

Input parameters:

- `cnpj` (string): Optional: filter by payer CNPJ digits only
- `cpf` (string): Optional: filter by payer CPF digits only
- `from` (string, required): Start timestamp ISO-8601 (inicio)
- `page` (number): Page number
- `page_size` (number): Items per page
- `to` (string, required): End timestamp ISO-8601 (fim)
- `txid` (string): Optional: filter by txid of originating cob

### `register_dict_key` (~117 tokens)

Register a new DICT key for one of the merchant's Santander accounts. BACEN enforces ownership proof (the account document must match the key for CPF/CNPJ keys).

Input parameters:

- `account` (string, required): Merchant agência-conta that the key will point to
- `account_type` (string): CACC (checking) | SVGS (savings)
- `key` (string): Key value (omit for EVP — BCB generates a UUID)
- `key_type` (string, required): CPF | CNPJ | EMAIL | PHONE | EVP

### `delete_dict_key` (~47 tokens)

Remove (unregister) a DICT key previously registered for the merchant. Does not affect received Pix that used the key historically.

Input parameters:

- `key` (string, required): DICT key to remove

### `download_boleto_pdf` (~78 tokens)

Fetch the PDF (second copy / segunda via) of a registered boleto. Returns a base64-encoded PDF payload or a time-limited URL, depending on Santander's workspace config.

Input parameters:

- `bill_id` (string, required): Santander bill_id / bank_slip identifier
- `workspace_id` (string, required): Santander workspace_id that owns the boleto

### `get_account_balance` (~36 tokens)

Get current available and blocked balance for a Santander merchant account.

Input parameters:

- `account` (string, required): Agência-conta identifier of the merchant account

### `send_ted` (~127 tokens)

Initiate a TED transfer from a Santander merchant account to an account at another bank. For same-day settlement within the TED cutoff window.

Input parameters:

- `amount` (string, required): Amount in BRL major units, e.g. '5000.00'
- `idempotency_key` (string, required): Merchant-side idempotency key (UUID recommended)
- `payee` (object, required): Payee bank account
- `payer_account` (string, required): Merchant account to debit (agência-conta)
- `purpose_code` (string): BACEN TED finalidade code (default 1 - Crédito em Conta)

### `transfer_internal` (~126 tokens)

Transfer between two Santander accounts (TEF / mesma instituição). Settles instantly and is fee-free for most covenants.

Input parameters:

- `amount` (string, required): Amount in BRL major units
- `description` (string): Free-text description on the statement
- `idempotency_key` (string, required): Merchant-side idempotency key (UUID recommended)
- `payee_account` (string, required): Destination Santander account (agência-conta)
- `payee_document` (string): Destination owner CPF/CNPJ digits only
- `payer_account` (string, required): Source merchant account (agência-conta)

### `create_openfinance_consent` (~156 tokens)

Create an Open Finance consent (BACEN-regulated) for data access or payment initiation against a third-party's Santander account. Returns a consent_id and authorization_url the end user must approve.

Input parameters:

- `consent_type` (string, required): DATA (read account info) | PAYMENT (initiate a Pix)
- `expiration` (string): Consent expiration ISO-8601 (max 12 months for data)
- `payment` (object): Required for consent_type=PAYMENT: { amount, creditor: { document, name, account } }
- `permissions` (array): Open Finance permission strings, e.g. ['ACCOUNTS_READ','RESOURCES_READ']
- `user_document` (string, required): End-user CPF/CNPJ digits only

### `arrecadacao_pay` (~145 tokens)

Pay a utility, tax, or concessionária bill via Santander Arrecadação / Pagamento de Contas. Works with barcode (código de barras) or linha digitável.

Input parameters:

- `amount` (string): Amount in BRL major units. Required when the barcode does not carry a fixed amount.
- `barcode` (string, required): 44-digit barcode or 47/48-digit linha digitável (digits only)
- `due_date` (string): Due date ISO-8601 (for validation against the barcode)
- `idempotency_key` (string, required): Merchant-side idempotency key (UUID recommended)
- `payer_account` (string, required): Merchant account to debit

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/codespar-mcp-santander/codespar-mcp-santander#diagnostics

## Score history

- 2026-08-04: 69
- 2026-08-03: 65
- 2026-08-02: 65
- 2026-08-01: 26
- 2026-07-31: 21
- 2026-07-30: 46
- 2026-07-28: 46
- 2026-07-27: 46

## Links

- npm package: https://www.npmjs.com/package/@codespar/mcp-santander
- Socket report: https://socket.dev/npm/package/@codespar/mcp-santander
- Repository: https://github.com/codespar/mcp-dev-latam
- Changelog RSS feed: https://verifymcp.io/servers/codespar-mcp-santander/codespar-mcp-santander/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/codespar-mcp-santander/codespar-mcp-santander/changelog.json
- HTML version of this page: https://verifymcp.io/servers/codespar-mcp-santander/codespar-mcp-santander