Skip to main content
Glama

AI agents can now pay for things: API credits, SaaS seats, datasets, cloud resources, invoices. Every bank, card issuer and payment provider gives them a different API, and none of them knows why the agent is spending. That's how you end up with:

  • πŸ” A checkout page hangs, the agent retries, and you pay twice.

  • πŸ“† A $15 "trial" fits under the $50 cap and auto-renews forever.

  • 🀷 Finance asks "what was this charge?" and nobody can say why the agent bought it.

PurseString is a self-hosted MCP server that gives agents one interface to financial services and enforces your spending rules before anything is executed. The agent declares what it wants to pay for, why, and what it tried first. PurseString checks that against your policies.yaml, blocks duplicates, pauses risky spend for a human in Slack or Discord, records the decision, and only then executes it on the right provider.

WARNING

v0.1 alpha. PurseString issues real Lithic cards: use a production Lithic key and set adapter.lithic.environment: production. It's early software, so start with low limits. Tested end to end on the Lithic sandbox: card issue, duplicate-request replay, auto-close after 10 minutes, and real-time charge approval (answered in under 3 ms; try it yourself). Tell us what breaks in issues.

πŸ† PayPal AI Hackathon: how PurseString uses PayPal and AI

Try the live demo: no login needed. You play the human approver while an agent tries to buy things and issue refunds on the PayPal sandbox.

  • PayPal Agent Toolkit / PayPal MCP server (@paypal/mcp): PurseString runs PayPal's own MCP server behind itself and re-exposes its tools to the agent, with guardrails. Read-only tools pass through. Refunds are auto-run, paused for a human, or refused, depending on the amount. Accepting a dispute or cancelling always needs a human. A retried refund returns PayPal's first answer instead of refunding twice.

  • PayPal Payouts API (PayPal and Venmo): the send_payment tool pays vendors. The recipient comes from a payee directory in policies.yaml, never from the agent, so a prompt injection has no address to swap in. The intent ID is sent as PayPal-Request-Id, so a payout can't happen twice.

  • PayPal OAuth (client credentials): PurseString keeps the client secret, and PayPal's MCP server only ever sees short-lived access tokens.

  • AI: the agent being governed is any MCP-capable model. We built and tested with Claude (Claude Desktop and Claude Code), and the project speaks the Model Context Protocol through the official TypeScript SDK. Claude Code was also used as a pair programmer for the code, tests and docs.

  • Render: the hosted demo runs on Render, deployed from this repo's Dockerfile and render.yaml.

Setup in the PayPal sandbox takes about 5 minutes: see docs/paypal.md.

Related MCP server: spendveto

🧩 What it does, and what works today

Status

πŸ”Œ Connect

Banks, payment providers and card issuers behind one MCP interface, through community-built adapters.

🟑 Virtual cards via Lithic (sandbox and production), Privacy.com cards funded from your own bank account and Airwallex cards for businesses outside the US (both new, untested with a live account), PayPal and Venmo payouts straight to a vendor's account on file, Stripe Connect, RazorpayX and Modern Treasury payouts (new, tested against stubbed API responses only), x402 pay-per-request APIs in USDC (new, testnet by default, not yet run against a live facilitator), guardrails in front of PayPal's own MCP server (refunds, disputes, cancellations), plus a mock rail for testing. Not yet: your existing card directly, and other providers (see roadmap).

πŸ›‘οΈ Govern

Budgets, vendor allow and block lists, and human approvals, defined once and enforced the same way on every provider.

βœ… Live: policies.yaml, per-agent daily budgets, Slack / Discord approval pause, per-purchase rail routing, a kill switch for one agent or all of them that also trips itself when an agent keeps re-buying the same thing.

πŸ’³ Execute

Authorized payments and other supported financial operations.

🟑 Single-use and merchant-locked virtual cards today. Bank transfers (ACH / wire) are on the roadmap (#16).

πŸ”’ Protect

No duplicate operations, safe handling of uncertain payment states, and a record of every decision.

βœ… Live: idempotency keys, safe retries after a hung checkout, real-time checks on every card charge, cards that close after 10 minutes, hash-chained audit log (pursestring verify-log).

🌍 Expand

Developers add integrations for more providers and countries.

βœ… Live: a small adapter interface and a contributor guide. The first community adapters are up for grabs.

βœ… live today Β· 🟑 partly live, more on the roadmap

Govern and Protect in detail

πŸ›‘ No double charges

Every intent gets a deterministic key, SHA256(agent_id, task_id, vendor, amount). Retry inside 30 minutes and you get the same card back, not a second transaction.

πŸ“† No surprise subscriptions

Anything marked is_recurring goes to a human, whatever the amount. Approved subscriptions get a merchant-locked card with a monthly cap, so they can't be reused elsewhere.

πŸ™‹ Approve by risk, not by dollar amount

Small, one-time, allowlisted spend is auto-approved. Recurring, over-threshold or unknown-vendor spend pauses and pings Slack or Discord. Blocklisted vendors and spend over the hard cap are refused outright.

⚑ Every charge checked as it happens

With just-in-time authorization, the card issuer asks PurseString before each charge goes through. Only a charge that matches the approved intent (right card, right amount, first use, still live) is approved.

⏱️ Cards that close themselves

Single-use cards close 10 minutes after issue, so a leaked number is worthless.

🧠 Intent before money

The agent must state the goal and the free alternatives it tried. A vague goal or no alternatives means a human looks first.

πŸ“Ό A black box recorder for every decision

Goal, alternatives, the agent's reasoning, every rule and how it ruled, who approved, and what was executed, as append-only JSON lines. Card numbers are never written to disk.

πŸ”€ One policy, routed per provider

routes in policies.yaml picks the provider per purchase by amount, vendor or recurrence, so the same rules apply wherever the money moves.

🏠 Self-hosted, Apache 2.0

Runs on your laptop or in your VPC. Your financial credentials never leave your infrastructure.

🀝 Use it with your rail, not instead of it

PurseString doesn't replace your card issuer or bank. It's the interface and policy layer on top, so the same rules apply whichever provider moves the money.

Card issuer controls(Ramp, Stripe Issuing, Lithic)

PurseString on top

Spend caps and merchant locks

βœ…

βœ… (enforced on the card it issues)

One policy across several rails

Each rail has its own

βœ…

Agent must declare goal and alternatives

βœ…

Intent-level duplicate-charge protection

βœ…

Real-time approval checked against why the card was issued

βœ…

Recurring charges always routed to a human

βœ…

Reasoning-level audit trail ("why did it buy this?")

βœ…

Open source, self-hosted

βœ…

πŸš€ Quickstart

New here? Try it in 10 minutes with Claude Desktop and test cards: an auto-approved purchase, a blocked double charge, and a subscription that waits for your approval.

1. Add it to your MCP client. Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and most others use the same shape:

{
  "mcpServers": {
    "pursestring": {
      "command": "npx",
      "args": ["-y", "github:suseendar1414/pursestring"],
      "env": { "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/..." }
    }
  }
}

With Claude Code: claude mcp add pursestring -- npx -y github:suseendar1414/pursestring

With ChatGPT (developer mode) or claude.ai custom connectors: run it as a server and sign in with OAuth. See docs/chatgpt.md.

2. Write a policy. Run npx -y github:suseendar1414/pursestring init to get a commented policies.yaml, then edit the vendor allowlist. With no file, safe defaults apply: auto-approve under $20 on allowlisted vendors, a human above $50 or for anything recurring.

3. Ask your agent to buy something. It calls the tools below. Out of the box it uses the mock rail (test card numbers, no money moves). Set LITHIC_API_KEY to issue real Lithic cards: a sandbox key for testing, or a production key plus adapter.lithic.environment: production for live cards.

Prefer Docker? docker compose up -d gives you the server over HTTP at http://localhost:8787/mcp. See docs/deploy.md.

🧰 Tools your agent gets

Tool

What it does

check_policy_compliance

Dry run. Returns auto_approve, require_approval or deny, and every rule checked. Nothing is issued, nobody is pinged.

submit_purchase_intent

Declares the purchase. Policy decides; risky spend pauses and pings a human. Identical retries return the original intent.

request_ephemeral_card

Issues a single-use card capped at the approved amount, only for an approved intent. Retries return the same card.

get_intent_status

Checks status, or waits up to 5 minutes for a human to approve or deny.

What the agent sends:

{
  "agent_id": "invoice-bot",
  "task_id": "102",
  "task_goal": "Parse invoice PDF for task #102",
  "vendor_domain": "pdfocr.io",
  "amount": 15.00,
  "is_recurring": true,
  "alternatives_attempted": ["PyPDF2 (failed OCR)"]
}

What it gets back:

{
  "intent_id": "int_19099cd4d52542c2a33f",
  "status": "pending_approval",
  "summary": "Needs human approval: require_approval.recurring (recurring charge: will renew until cancelled)",
  "next_step": "Paused for human approval. Do not buy another way. Call get_intent_status ..."
}

A human approves with the Slack Approve button, from the terminal, or through the HTTP approval API. When Slack or Discord is set up, the terminal needs the one-time code from that message, so an agent with a shell can't approve its own purchase (who can approve):

$ npm i -g github:suseendar1414/pursestring
$ pursestring pending
int_19099cd4d52542c2a33f  15.00 USD  pdfocr.io (recurring)  agent=invoice-bot task=102
$ pursestring approve int_19099cd4d52542c2a33f --code 7KQ2M-X9D4T --note "ok for one month"

πŸ—οΈ How it works

flowchart LR
  A["AI agent<br/>Claude Β· Cursor Β· LangGraph Β· CrewAI"] -->|"intent: goal, amount,<br/>vendor, recurring, alternatives"| S
  subgraph S["PurseString"]
    direction TB
    I["Intent check"] --> D["Idempotency lock"] --> P["Policy engine<br/>auto Β· human Β· deny"] --> L["Decision log"]
  end
  P -.->|"risky spend"| H["Slack / Discord<br/>human approves"]
  S -->|"approved only, routed by policy"| R["Payment adapters"]
  R --> C1["BaaS virtual cards<br/>Lithic Β· Highnote* Β· Marqeta*"]
  R --> C2["Corporate cards<br/>Amex*"]
  R --> C3["Bank transfers<br/>ACH / wire*"]
  C1 -.->|"real-time: approve this charge?"| S

* on the roadmap, contributions welcome

Deep dive: docs/how-it-works.md. Policy reference: docs/policies.md.

πŸ—ΊοΈ Roadmap

  • MCP server (stdio + Streamable HTTP), intent schema, policy engine

  • OAuth sign-in for remote clients (ChatGPT developer mode, claude.ai connectors)

  • Idempotency locks, single-use cards, decision log

  • Slack / Discord approval pause, CLI and HTTP approve/deny

  • One-click Slack approve/deny buttons, and one-time approval codes so agents can't approve themselves

  • Mock rail, Lithic virtual cards, Docker image

  • Just-in-time authorization (Lithic ASA), cards that close after 10 minutes

  • Policy-based rail routing

  • Connect more providers: Highnote (#13), Marqeta (#14), Amex corporate cards (#15), the user's own Visa / Mastercard via Visa Intelligent Commerce and Mastercard Agent Pay (#20), Stripe Issuing (#1), x402 / USDC (#2)

  • Existing bank accounts: ACH / wire transfers from the company's own account, with reconciliation of uncertain transfer states (#16)

  • More countries: SEPA and local rails, contributed as adapters

  • Per-agent and per-team policies

  • Audit log viewer

  • Framework examples: LangGraph, CrewAI, Vercel AI SDK, OpenAI Agents SDK

Want one of these? Grab a good first issue and comment "I'd like to take this".

🧭 Open core

PurseString is open core. Everything in this repository is free and stays Apache 2.0: the MCP server, policies.yaml, the decision log, the approval pause, and the card adapters. A hosted PurseString Cloud for teams running agents in production is planned on top of it:

Community core (this repo, free)

PurseString Cloud (planned)

Self-hosted MCP server, YAML policies

Audit dashboard with visual decision trees for every charge

Local JSON decision log

One-click Slack / Teams approvals

Slack / Discord approval pause

Role-based access: policies per department, project or agent squad

Sandbox card adapters (Lithic, Stripe Issuing)

Enterprise rails: Amex, bank ACH / wires, ERP purchase orders

The full product vision is in docs/VISION.md.

πŸ’¬ Community

If PurseString saves you from a double charge, a ⭐ helps other agent builders find it.

πŸ”’ Security

PurseString handles payment credentials, so it's built to be read: no telemetry, no outbound calls except to your configured rail and webhooks, and card numbers are never written to state or logs. Found a vulnerability? Please follow SECURITY.md instead of opening a public issue.

πŸ“„ License

Apache 2.0. Use it commercially, fork it, run it in your VPC. Apache 2.0 includes an explicit patent grant, which matters for anything that touches payments and is what enterprise security and legal teams expect to see.

Available Tools

5 tools
check_policy_complianceCheck policy compliance (dry run)A
Read-onlyIdempotent

Evaluate a purchase against the spend policy without submitting it. Returns the decision (auto_approve, require_approval or deny) and every rule that was checked. No card is issued and no human is pinged.

Inputs: amount (required), task_id (required), agent_id (required), task_goal (required), +5 more.

get_intent_statusGet intent statusB
Read-only

Check an intent's status. Pass wait_seconds (up to 300) to block until a human approves or denies it, which is how the agent pauses for human-in-the-loop approval.

Inputs: intent_id (required), wait_seconds.

request_ephemeral_cardRequest ephemeral cardA
Idempotent

Get a single-use virtual card for an approved intent, capped at the approved amount. Calling this again for the same intent_id inside the idempotency window returns the same card: safe to retry after a hung checkout.

Inputs: intent_id (required).

send_paymentSend paymentA
Idempotent

Pay an approved intent through a payout rail (PayPal, Venmo, Stripe Connect, RazorpayX or Modern Treasury). The approved amount goes to the vendor's account on file in the policy; you can't choose the recipient. Each intent is paid at most once: calling again returns the existing payment, so it is safe to retry.

Inputs: intent_id (required).

submit_purchase_intentSubmit purchase intentA
Idempotent

Declare a purchase before making it. Policy decides: auto-approve, pause for a human (Slack/Discord), or deny. Submitting the same agent_id + task_id + vendor + amount again inside the idempotency window returns the original intent instead of creating a second one.

Inputs: amount (required), task_id (required), agent_id (required), task_goal (required), +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool maps to a distinct stage of the spend lifecycle: policy dry-run, intent submission, status polling, card issuance, and payment. The only near-overlap is check_policy_compliance versus submit_purchase_intent, but the descriptions clearly distinguish a non-submitting evaluation from an actual declaration.

    Naming Consistency5/5

    All names use consistent snake_case with a clear verb_noun structure: check_policy_compliance, submit_purchase_intent, request_ephemeral_card, send_payment, get_intent_status. The pattern is predictable throughout.

    Tool Count5/5

    Five tools is well-scoped for this narrow spending-control workflow, with each tool earning its place. There are no redundant or trivial tools.

    Completeness4/5

    The core lifecycle is covered: policy check, intent creation, human-in-the-loop status wait, virtual card issuance, and payment. Minor gaps exist around canceling an intent or voiding a card, but the main agent workflow has no dead ends.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Governs AI agents' spending by enforcing budgets, approvals, and kill switches before any payment, providing an MCP interface for tool calls with policy checks.
      377 npm
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables human-in-the-loop authorization for AI agent transactions, allowing real-time approval or denial of purchases based on configurable spending limits, vendor blocklists, daily caps, and category restrictions.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to route PayPal money-moving requests through deterministic spending rules, AI injection and intent checks, human approvals, and tamper-evident audit logging.
      16 npm
      MIT