bonanza-mcp 0.1.0

MCP server for AI agent payments — spending firewall, budget checks, and approval flows via the Model Context Protocol

💳 Bonanza MCP

MCP server for AI agent payments — spending firewall, budget checks, and approval flows

Use Bonanza's spending firewall directly from Claude, GPT, or any MCP-compatible AI agent. Check budgets, evaluate payments, approve spending, and audit transactions — all through natural language.

Why?

AI agents are making payments, but they need guardrails. Bonanza MCP brings our spending firewall to the Model Context Protocol — the standard way AI models interact with tools.

Instead of writing custom code, your AI agent can simply call:

"Check if I can pay $5.00 for weather data" "What's my remaining budget?" "Approve payment to api.premium-data.com" "Show my spending history"

Installation

pip install bonanza-mcp

With x402 protocol support:

pip install bonanza-mcp[x402]

Quick Start

1. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bonanza": {
      "command": "bonanza-mcp",
      "args": ["--max-budget", "10.00", "--require-approval-above", "5.00"]
    }
  }
}

2. Use in conversation

You: Check my budget
Claude: Your current spending is $2.50 out of $10.00 (25%). You have $7.50 remaining.

You: Can I pay $3.00 for API data from weather.com?
Claude: ✅ Payment approved: $3.00 to weather.com
   Reason: All checks passed
   Risk level: LOW (0.20)
   Remaining budget: $4.50

You: Pay $8.00 for premium AI analysis
Claude: ❌ Payment blocked: Session budget exceeded: $2.50 + $8.00 > $10.00

You: Pay $6.00 for verified data from api.trusted.com
Claude: ⏳ Requires human approval: $6.00 exceeds the approval threshold ($5.00)
   Approval URL: https://bonanza-labs.com/firewall/approve/abc-123

3. Use programmatically

from bonanza_mcp import BonanzaMCPServer

server = BonanzaMCPServer(
    max_budget_usd=10.00,
    require_approval_above=5.00,
    trusted_vendors=["api.weather.com", "api.data.gov"],
    allowed_networks=["base", "solana"],
)

# Run as MCP server
server.run()

MCP Tools

Tool	Description
check_budget	Show current spending and remaining budget
evaluate_payment	Evaluate a payment against firewall policy
approve_payment	Approve a pending payment
reject_payment	Reject a pending payment
spending_history	View recent spending with filters
set_budget	Update the budget for the current session
add_vendor	Add a vendor to the trusted list
remove_vendor	Remove a vendor from the trusted list
risk_assessment	Assess risk level for a vendor/amount

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│  AI Agent   │────▶│  Bonanza MCP     │────▶│  Firewall   │
│  (Claude/   │     │  Server           │     │  Engine     │
│   GPT/...)  │     │                  │     │             │
└─────────────┘     │  ┌────────────┐  │     │  ┌────────┐ │
                    │  │ Budget     │  │     │  │ Policy  │ │
                    │  │ Check      │──┼────▶│  │ Engine  │ │
                    │  ├────────────┤  │     │  └────────┘ │
                    │  │ Risk       │  │     │             │
                    │  │ Score      │  │     │  ┌────────┐ │
                    │  ├────────────┤  │     │  │ Audit   │ │
                    │  │ Vendor     │  │────▶│  │ Log     │ │
                    │  │ Allowlist  │  │     │  └────────┘ │
                    │  └────────────┘  │     └─────────────┘
                    └──────────────────┘

Comparison

Feature	bonanza-mcp	AgentBudget MCP	Lightning MCP
Budget limits	✅	✅	❌
Vendor allowlist	✅	❌	❌
Risk scoring	✅	❌	❌
Human approval queue	✅	❌	❌
Stripe checkout	✅	❌	❌
x402 integration	✅	❌	❌
Crypto (USDC/SOL)	✅	❌	✅
Audit trail	✅	✅	❌
MCP protocol	✅	❌	✅

Requirements

• Python 3.10+
• mcp>=1.0.0
• pydantic>=2.0
• httpx>=0.24

License

Apache License 2.0 — see LICENSE for details.

Links

• Website: bonanza-labs.com
• Live Demo: bonanza-labs.com/firewall
• x402 Adapter: pypi.org/project/bonanza-x402
• MCP Protocol: modelcontextprotocol.io
• GitHub: github.com/c6zks4gssn-droid/bonanza-labs-website

---

Built by Bonanza Labs 🧨