mcp-stone — Claude Code MCP server: Stone banking and Pix
An MCP server that puts Stone Open Bank inside your coding agent: payments, Pix, transfers, receivables. Useful when the assistant has to move money, not just draft code for it.
claude mcp add mcp-stone -e STONE_CLIENT_SECRET=<STONE_CLIENT_SECRET> -- npx -y @codespar/mcp-stoneWhat mcp-stone does
@codespar/mcp-stone ships 21 tools. They cover account balance, statements and transaction history, outbound payments and bank transfers, Pix payouts and Pix cob charges with a QR code, boleto issuance, refunds and cancellation of authorized transactions, plus card tokenization. On the acquiring side you get credit and debit card charges, a search across future credits, anticipation limits, creating an anticipation, and a list of POS terminals with their status. Two more tools register and list webhook endpoints.
Sign-in uses OAuth2 client credentials and the server refreshes the token on its own. You need STONE_CLIENT_ID and STONE_CLIENT_SECRET from the Stone developer portal. Without both, no tool can authenticate. Point STONE_BASE_URL and STONE_AUTH_URL at the sandbox hosts to test safely.
Up to release 0.2.2 the token request went to login.openbank.stone.com.br, a host that does not exist, so every call died at authentication. On an older build set STONE_AUTH_URL yourself before you rely on any payment tool.
What it helps with
- read the Stone account balance from a chat with the agent
- issue a customer charge as a Pix cob or a boleto
- refund a settled charge or cancel one still uncaptured
- check anticipation limits and upcoming receivables
- see whether a POS terminal is online and register a webhook
Example prompts for the agent
- Show the balance and last month's statement, then create a 250 BRL boleto for the client in my notes.
- Create an 80 BRL Pix cob, give me the QR code, and check its status in an hour.
- What are this merchant's anticipation limits, and which terminals are offline right now?
How to install mcp-stone
Platform CLI
claude mcp add mcp-stone -e STONE_CLIENT_SECRET=<STONE_CLIENT_SECRET> -- npx -y @codespar/mcp-stoneReplace <…> with your own values
Platform CLI
codex mcp add stone --env STONE_CLIENT_SECRET=<STONE_CLIENT_SECRET> -- npx -y @codespar/mcp-stoneReplace <…> with your own values
Config file
{
"mcpServers": {
"stone": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-stone"
],
"env": {
"STONE_CLIENT_SECRET": "<STONE_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"stone": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-stone"
],
"env": {
"STONE_CLIENT_SECRET": "<STONE_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e STONE_CLIENT_SECRET=<STONE_CLIENT_SECRET> stone npx -y @codespar/mcp-stoneReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-stone
How do I install mcp-stone in Claude Code?
Run claude mcp add mcp-stone -e STONE_CLIENT_SECRET=<STONE_CLIENT_SECRET> -- npx -y @codespar/mcp-stone. Pass STONE_CLIENT_ID the same way with -e, or set both keys in your environment.
What does mcp-stone do?
It authenticates against the Stone Open Bank API over OAuth2 and exposes tools for balance, statements, payments, transfers, Pix, boleto, card acquiring, anticipation and terminals.
What does the server need before it works?
OAuth2 credentials from the Stone developer portal, set as STONE_CLIENT_ID and STONE_CLIENT_SECRET. For testing, switch STONE_BASE_URL and STONE_AUTH_URL to the sandbox addresses.
