💰

io.github.vrllrv/junto-mcp

The payment protocol for people and agents. One MCP server, any payment rail.

0 installs

Trust: 37 — Low

Finance

Ask AI about io.github.vrllrv/junto-mcp

Powered by Claude · Grounded in docs

I know everything about io.github.vrllrv/junto-mcp. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Documentation

Junto

The payment protocol for people and agents.

Send and receive money through any AI assistant. Any payment rail. Built-in guardrails.

Named after Benjamin Franklin's Junto — a society of tradesmen who built civic infrastructure together. Different providers, same table, mutual benefit.

Why

AI assistants are starting to move real money — paying invoices, splitting bills, sending transfers. But every payment provider has a different API, different auth, different settlement times. Nobody should have to teach their assistant how Pix works vs Stripe vs Wise.

Junto fixes that with one MCP server that:

Exposes a universal payment toolkit to any MCP-compatible client (Claude, Cursor, custom agents)
Routes to the right provider based on currency, country, and rail
Enforces spending limits so agents can't go rogue
Supports human-in-the-loop confirmation for high-value transactions
Logs every action for audit and accountability

Tools

Tool	Description
`pay`	Send money to a destination (Pix key, email, IBAN, etc.)
`charge`	Create a payment request / invoice / QR code
`status`	Check payment status by correlation ID
`refund`	Reverse a completed transaction
`balance`	Check available funds on a provider
`providers`	List configured providers and their capabilities
`limits`	Show spending limits and today's usage

Quick Start

npm install -g junto-mcp

Set your provider API key:

export WOOVI_APP_ID="your-woovi-app-id"

Run as CLI (human mode):

junto pay 25.00 maria@email.com
junto charge 10.00 "Coffee"
junto balance

Run as MCP server (for AI clients):

junto --mcp

Portuguese / Portugues

Junto auto-detects your system language, or set manually:

JUNTO_LANG=pt-BR junto ajuda
junto pagar 25.00 maria@email.com
junto cobrar 10.00 "Cafe"
junto saldo

See CLI.md for the full command reference in both languages.

Add to Claude Desktop or Cursor

{
  "mcpServers": {
    "junto": {
      "command": "npx",
      "args": ["-y", "junto-mcp"],
      "env": {
        "WOOVI_APP_ID": "your-woovi-app-id"
      }
    }
  }
}

That's it. Your AI assistant now has payment tools.

Guardrails

All amounts are in cents (smallest currency unit).

Setting	Env Var	Default	Meaning
Daily limit	`JUNTO_DAILY_LIMIT`	50000 (R$500)	Max total spend per day
Per-tx max	`JUNTO_PER_TX_MAX`	20000 (R$200)	Max single transaction
Confirm above	`JUNTO_CONFIRM_ABOVE`	5000 (R$50)	Ask human before sending
Allowed providers	`JUNTO_ALLOWED_PROVIDERS`	(all)	Comma-separated allowlist
Allowed destinations	`JUNTO_ALLOWED_DESTINATIONS`	(all)	Comma-separated type allowlist

When an agent tries to send above the JUNTO_CONFIRM_ABOVE threshold, the server pauses and returns a confirmation prompt. The agent must relay this to the user and get approval before proceeding.

⚠️ Confirmation required

  Amount:      BRL 150.00
  To:          maria@email.com
  Reason:      Amount (15000 cents) exceeds confirmation threshold (5000 cents)

Please confirm with the user before proceeding.

Architecture

┌─────────────────────────────────────┐
│  MCP Client (Claude, Cursor, etc.)  │
└──────────────┬──────────────────────┘
               │ MCP Protocol (stdio)
┌──────────────▼──────────────────────┐
│           junto-mcp                 │
│                                     │
│  ┌───────────┐  ┌────────────────┐  │
│  │  Router    │  │  Guardrails    │  │
│  │  (picks    │  │  (spend caps,  │  │
│  │  provider) │  │  HITL confirm, │  │
│  │           │  │  audit log)    │  │
│  └─────┬─────┘  └────────────────┘  │
│        │                            │
│  ┌─────▼─────────────────────────┐  │
│  │  Provider Adapters            │  │
│  │  ┌────────┐ ┌──────┐ ┌────┐  │  │
│  │  │ Woovi  │ │Stripe│ │Wise│  │  │
│  │  └────────┘ └──────┘ └────┘  │  │
│  └───────────────────────────────┘  │
│                                     │
│  ┌───────────────────────────────┐  │
│  │  Audit Ledger (JSONL)         │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Providers

Provider	Region	Rails	Status
Woovi/OpenPix	Brazil	Pix	🟢 Live (tested with real Pix transactions)
Ebanx	Brazil + LATAM	Pix payouts, Boleto, Cards	🟡 Next
Belvo	Brazil	Open Finance (all banks)	🟡 Next
Stripe	Global	Cards, ACH, SEPA	🟡 Next
Wise	Global	Bank transfers	🔴 Planned
Mercado Pago	LATAM	Pix, Cards	🔴 Planned
PayPal	Global	Email-based	🔴 Planned

Why Woovi/Pix first?

Pix settles instantly (perfect for demos and real use)
Brazil's Central Bank mandates open APIs for payments
180M+ Pix users, 80B+ transactions in 2025
Pix Automático (launched June 2025) enables recurring payments
Low fees, no intermediaries
Verified: charge, status, and payment flows tested with real Pix transactions (March 2026)

Demo

You:   "Pay R$25 to maria@email.com via Pix"

Agent:  I'll send the following payment:
          Amount: R$ 25,00
          To: maria@email.com (Pix)
          Via: Woovi
        Shall I go ahead?

You:   "Yes"

Agent:  Done! Payment sent.
          Amount: R$ 25,00
          To: maria@email.com
          Via: Pix (Woovi)
          Status: Completed
          ID: junto-1739612345-a1b2c3

Adding a Provider

Each provider is a single file implementing the PaymentProvider interface:

// src/providers/your-provider.ts
import { PaymentProvider } from "../types.js";

export class YourProvider implements PaymentProvider {
  name = "your-provider";
  supportedCurrencies = ["USD"];
  supportedRails = ["card"];
  settlementTime = "1-3 days";

  async pay(req) { /* send money */ }
  async charge(req) { /* create invoice */ }
  async status(id) { /* check status */ }
  async refund(id) { /* reverse payment */ }
  async balance() { /* check funds */ }
  info() { /* return capabilities */ }
}

Copy src/providers/_template.ts to get started, then register your provider in src/index.ts.

Testing

npm test              # Guardrail unit tests
npm run test:smoke    # Full flow smoke tests (mock provider)

Live testing with real Pix

# Create a Pix charge (R$1.00)
WOOVI_APP_ID=your-key npx tsx test/live-pix.ts charge 100 "Test charge"

# Check status
WOOVI_APP_ID=your-key npx tsx test/live-pix.ts status <correlation-id>

# Send a Pix payment
WOOVI_APP_ID=your-key npx tsx test/live-pix.ts pay 100 user@email.com EMAIL

# Refund
WOOVI_APP_ID=your-key npx tsx test/live-pix.ts refund <correlation-id>

Interactive demo

npx tsx demo/demo.ts          # Full demo with typewriter narration + real API calls
npx tsx demo/demo.ts --fast   # Fast mode for rehearsals

Audit Log

Every transaction is logged to ~/.junto/audit-YYYY-MM-DD.jsonl:

{
  "timestamp": "2026-02-15T14:32:07Z",
  "type": "payment",
  "action": "pay",
  "tool": "pay",
  "amount": 2500,
  "currency": "BRL",
  "provider": "woovi",
  "destination": "maria@email.com",
  "status": "executed"
}

Roadmap

Contributing

We need help with:

Provider adapters — Ebanx, Stripe, Wise, Belvo, Mercado Pago, PayPal, UPI
Routing logic — Cheapest vs fastest vs most reliable provider selection
HITL patterns — Approval flows across different MCP clients
Security audit — Review of the guardrails and auth system
Multi-currency — FX handling, cross-border routing
Docs — Compliance and regulatory guides per region

License

MIT