About mcp-stone
mcp-stone is an MCP server for Stone, covering acquiring by card, Pix and boleto, anticipation of receivables, POS terminals and open banking. It is aimed at Brazilian merchants and their developers who want an AI client to handle charging and settlement tasks.
Key features
- 01Charge cards, Pix and boleto payments
- 02Refund or cancel transactions
- 03Request receivable anticipation and check limits
- 04List receivables and account transactions
- 05View POS terminal list and status
- 06Register webhooks for Stone events
Use cases
- 01Ask an agent for a merchant's anticipation limits and receivables
- 02Check whether POS terminals are online
- 03Create Pix charges or boleto collections from an AI client
MCP support
This project is an MCP server that exposes 21 tools to MCP clients for acquiring, transfers, receivables, terminals and webhooks through the Stone API.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @codespar/mcp-stoneSTONE_CLIENT_SECRETSecretAPI key for stoneLocal servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
21Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| account_id | string | Yes | Account ID |
Details
From the project README@codespar/mcp-stone
MCP server for Stone — acquiring (card / Pix / boleto), anticipations, receivables, terminals, and open banking
Quick Start
Claude Desktop
Add to ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"stone": {
"command": "npx",
"args": ["-y", "@codespar/mcp-stone"],
"env": {
"STONE_CLIENT_ID": "your-client-id",
"STONE_CLIENT_SECRET": "your-client-secret"
}
}
}
}
Claude Code
claude mcp add stone -- npx @codespar/mcp-stone
Cursor / VS Code
Add to .cursor/mcp.json or .vscode/mcp.json:
{
"servers": {
"stone": {
"command": "npx",
"args": ["-y", "@codespar/mcp-stone"],
"env": {
"STONE_CLIENT_ID": "your-client-id",
"STONE_CLIENT_SECRET": "your-client-secret"
}
}
}
}
Tools (21)
| Tool | Purpose |
|---|---|
get_balance | Get account balance |
list_transactions | List account transactions |
get_statement | Get account statement for a period |
create_payment | Create a payment via Stone |
get_payment | Get payment details by ID |
list_payments | List payments with optional filters |
create_transfer | Create a bank transfer (internal or external) |
create_pix_payment | Create a Pix payment (outbound) via Stone |
create_pix_charge | Create a Pix charge (QR Code / cob) to receive a payment |
create_boleto | Create a boleto bancário for charging a customer |
create_card_charge | Charge a credit or debit card (Stone acquiring) |
tokenize_card | Tokenize a card to PCI-safe token for later charging |
refund_transaction | Refund a settled transaction (full or partial) |
cancel_transaction | Cancel an authorized (not-yet-captured) transaction |
create_anticipation | Anticipate future receivables (Stone's flagship 'antecipação') |
get_anticipation_limits | Get current anticipation limits (max / min / available) for a merchant |
list_receivables | Search receivables (future credits from card transactions) |
list_terminals | List physical Stone / TON terminals for a merchant |
get_terminal_status | Get current status of a specific POS terminal (online / offline / last seen) |
register_webhook | Register a webhook endpoint for Stone events |
list_webhooks | List registered webhook endpoints |
Authentication
Stone uses OAuth2 client credentials for authentication. The server automatically manages token refresh.
Sandbox / Testing
Stone provides a sandbox via the developer portal.
Get your credentials
- Go to Stone Open Bank Documentation
- Register as a developer
- Create an application to get OAuth2 credentials
- Set the environment variables
Environment Variables
| Variable | Required | Description |
|---|---|---|
STONE_CLIENT_ID | Yes | OAuth2 client ID |
STONE_CLIENT_SECRET | Yes | OAuth2 client secret |
STONE_BASE_URL | No | Override base URL (default https://api.openbank.stone.com.br/api/v1; sandbox https://sandbox-api.openbank.stone.com.br/api/v1) |
STONE_AUTH_URL | No | Override the OAuth2 token URL (default https://accounts.openbank.stone.com.br/auth/realms/stone_bank/protocol/openid-connect/token; sandbox https://sandbox-accounts.openbank.stone.com.br/auth/realms/stone_bank/protocol/openid-connect/token). Up to 0.2.2 the token call went to login.openbank.stone.com.br, which does not exist, so every tool failed at authentication. |
Roadmap
v0.3 (planned)
list_pix_keys— List registered Pix keys for a merchantcreate_recipient— Marketplace / split recipientscreate_transfer_batch— Batch transfer processingget_boleto— Fetch boleto detailscreate_scheduled_payment— Schedule future-dated paymentslist_payouts— List anticipation / settlement payouts
Want to contribute? Open a PR or request a tool.
Links
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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.