Documentation

Connecting agents to AgentPays

Everything you need to give your AI agent a payment capability.

Quick start

AgentPays gives AI agents a secure, controllable wallet through the Model Context Protocol (MCP). Agents request purchases via MCP tools; you set per-agent budgets, spending limits, and merchant rules that are enforced automatically. Requests below your auto-approve threshold go through instantly — anything above it lands in your review queue. Once approved, the agent receives the last 4 digits of a single-use virtual Mastercard and a secure, time-limited link to view the full card details.

Setup

1

Create an account

Sign up at agentpays.dev.

2

Connect your Privacy.com account

AgentPays issues single-use virtual Mastercards through Privacy.com when a purchase is approved. Sign up for a Privacy.com account, then go to Settings and paste your Privacy.com API key to enable card issuance.

3

Create an agent

Go to Agents → Create agent. Give it a name, set an auto-approve threshold, and configure spend rules. After creating the agent, copy the API key — it is only shown once. You only need it for the API key connection method below; OAuth users can skip this step.

4

Connect your AI assistant using one of the methods below

OAuth is recommended for Claude Desktop, Claude.ai, and ChatGPT — no API key required. Use the API key method for Claude Code, Codex, or custom agent frameworks.

MCP configuration

MCP endpoint: https://agentpays.dev/api/mcp

OAuth connection

Recommended

For Claude Desktop, Claude.ai, and ChatGPT. No API key required — authentication happens through a sign-in flow on first use.

Claude Desktop

Add to claude_desktop_config.json, then restart Claude Desktop. A browser window will open on first use to complete sign-in.

json
{
  "mcpServers": {
    "agentpays": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://agentpays.dev/api/mcp"
      ]
    }
  }
}

Claude.ai

  1. 1. Go to Settings → Connectors → Add custom connector
  2. 2. Enter AgentPays as the name and https://agentpays.dev/api/mcp as the URL
  3. 3. Click Add and complete the sign-in flow when prompted

ChatGPT

  1. 1. Go to Settings → Apps and Connectors → Create App
  2. 2. Enter AgentPays as the name and https://agentpays.dev/api/mcp as the URL
  3. 3. Complete the OAuth flow

API key connection

For Claude Code, Codex, or custom agent frameworks. Requires an API key from the agent's settings page.

json
{
  "mcpServers": {
    "agentpays": {
      "url": "https://agentpays.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with the full key shown when you created the agent.

Available tools

request_purchaseSubmit a purchase request

Input fields

merchant_urlstringrequiredMerchant domain (e.g. amazon.com, aws.amazon.com). Used to enforce the per-agent allowed/blocked domain rules with subdomain matching — allowing amazon.com also allows aws.amazon.com and smile.amazon.com.
amountnumberrequiredPurchase amount in the specified currency
descriptionstringrequiredWhat is being purchased
justificationstringrequiredWhy this purchase is needed — used for human review and auto-approval decisions
merchant_namestringHuman-readable merchant name (e.g. "AWS", "GitHub"). Descriptive only — not used for allow/deny decisions.
currencystringISO 4217 currency code, defaults to USD
category_hintstringMerchant category slug (e.g. cloud_compute, software_saas)

Possible responses

approvedIncludes request_id and a virtual_card object with the card's last4 digits and a secure view_url for retrieving the full card number, expiry, and CVC. The link expires 20 minutes after approval.
deniedIncludes reason explaining why the request was rejected (limit exceeded, merchant blocked, etc.) and an optional suggestion for how to proceed.
pending_reviewThe request exceeds the auto-approve threshold and is waiting for human review. Includes request_id and estimated_wait. Use check_status to poll for a decision.
check_statusCheck the status of a pending purchase request

Input fields

request_idstringrequiredThe request_id returned by request_purchase

Possible responses

approvedSame as request_purchase — includes the card's last4, a secure view_url for retrieving full details, and card_expires_at.
deniedIncludes reason with the denial explanation.
pending_reviewStill awaiting a decision. Continue polling.
get_spending_summaryGet current spending vs. configured limits

No input required.

Response fields

daily_spend / daily_limitSpend so far today vs. the configured daily cap (only present if a daily limit is set)
weekly_spend / weekly_limitSpend so far this week vs. the configured weekly cap
monthly_spend / monthly_limitSpend so far this month vs. the configured monthly cap
total_spend / total_budgetLifetime spend vs. the configured total budget

Security

AgentPays sits between an AI agent and your real funding source. The design goal is straightforward: even if the agent is compromised, prompt-injected, or simply wrong, the worst it can do is spend one approved single-use card. The sections below describe the threats we explicitly defend against, the mechanisms we use, and the things we do not claim to solve.

Threat model

Giving an LLM agent access to a payment instrument opens a specific set of failure modes. These are the ones we built around:

Credential exfiltration via prompt injection

A malicious tool result, web page, or document instructs the agent to leak its payment credentials to an attacker-controlled destination.

Compromised or malfunctioning agent

An agent that has been jailbroken, tampered with, or is simply behaving incorrectly drains funds at full speed against any stored payment method.

Rogue purchases at non-approved merchants

The agent decides — or is convinced — to spend at a merchant the operator never intended to authorize.

Replay with leaked card details

Card details captured from logs, screenshots, or shared context get reused later for unauthorized charges.

Card data persisting in agent memory and logs

Full PANs, expiry dates, and CVCs end up in long-lived agent context, transcript exports, tool-call traces, or third-party log sinks where they remain useful long after the original purchase.

How AgentPays mitigates each threat

Credential isolation

Your real credit card, bank account, and Privacy.com API key live behind AgentPays and are never sent to the agent or exposed through any MCP response. The agent only ever holds material it could not reuse against your underlying funding source.

Single-use virtual cards

Every approved purchase generates a new virtual Mastercard scoped to that one transaction amount. After it is charged once, it is dead. There is no persistent card the agent can spend against tomorrow.

Out-of-band card delivery

Card number, expiry, and CVC never appear in the MCP response itself. The response carries only the last 4 digits and a secure view URL. The agent must fetch the full details from that URL to complete checkout.

Short-lived view URL

The secure view link is signed with a time-limited token that expires 20 minutes after approval. A URL captured from logs or chat history past that window cannot be opened.

Bounded blast radius

If the view URL is opened by an attacker or the card details are scraped before expiry, the damage is capped at the single approved transaction amount at the approved merchant category. Your underlying funding source is untouched.

Server-side rule enforcement

Per-transaction limits, daily/weekly/monthly caps, allowed/blocked merchant domains, and the auto-approve threshold are evaluated by AgentPays before any card is issued. The agent cannot bypass a rule by lying about the request or ignoring the configuration.

Cross-agent aggregate caps

Per-agent limits don't stop two agents from each spending up to their own cap and collectively going past your real intent. AgentPays lets you set optional daily, weekly, and monthly aggregate caps that apply across every agent on your account combined — the rules engine checks them after per-agent rules and denies the request if the user-level total would exceed the cap. Configure them in Settings.

Three-tier approval architecture

Requests that pass all rules and are under the auto-approve threshold execute immediately. Requests above the threshold land in a human review queue and only issue a card after explicit approval. Any rule violation is a hard denial — no card is ever issued.

Full audit trail

Every request, approval, denial, rule evaluation, and card issuance is recorded and visible in the dashboard. There is a complete record of who asked for what, when, and how it was decided.

What we do not claim

The line between “what AgentPays defends” and “what is still your problem” matters more than marketing copy. Honest framing here:

The agent does see the single-use card

AgentPays does not hide all card data from the agent. To complete a checkout the agent has to open the view URL and read the card number, expiry, and CVC. What we isolate is your real funding source — credit card, bank account, Privacy.com API key — not the disposable card that exists for one transaction.

We do not prevent all prompt injection

An injected instruction can still cause the agent to call request_purchase with attacker-influenced inputs. Our defense is what happens after the call — rules, thresholds, human approval, and a single-use card with a bounded amount — not stopping the call from being attempted.

The view URL page can be scraped

A sufficiently capable attacker who obtains a live view URL within the 20-minute window can render the page and exfiltrate the card details. The mitigation is not page-level scrape resistance; it is that the card behind the page is single-use and scoped to one transaction, so the captured details are usable exactly once and only at the approved amount.

We rely on Privacy.com's underlying issuing security

AgentPays uses Privacy.com as the card issuer in v1. The security properties of card issuance, network authorization, and merchant controls come from Privacy.com. A failure in their issuing stack would affect AgentPays customers like any other Privacy.com user.

Example usage

Instructions for your agent's system prompt

When you need to purchase something, use the request_purchase tool. Always fill in the justification field with a clear explanation of why the purchase is necessary — this is required and used by the account owner when reviewing requests manually.

Always pass merchant_url set to the merchant's domain (e.g. amazon.com or aws.amazon.com). Allowed/blocked domain rules are enforced against this domain with subdomain matching, so an entry of amazon.com will also match aws.amazon.com.

If the response status is pending_review, save the request_id and poll check_status periodically until the owner approves or denies it.

If the response status is approved, the response includes a virtual_card object with the card's last4 digits and a secure view_url. Open the link to retrieve the full card number, expiry, and CVC. Card details are never returned directly in the MCP response; the viewing link expires 20 minutes after approval.

Before making a large purchase, call get_spending_summary to see whether any limits might block the request.

Ready to connect your first agent?

Get started free