create_card

Connect to https://mcp.agentcard.sh/mcp with the user’s connection token (or a buy_token for org-owned accounts).

What it does

The one card tool: get the user a virtual debit card for a purchase. Cards are live and charged for real when used. For a FIRST-TIME user it starts by putting the user’s OWN card in their Agentcard vault (any Visa, Mastercard, Amex, or Discover from any country, no identity verification (KYC), no balance funding): the call returns a secure link (vault_started); send it to the user (they type the card once and lock it with Face ID; Agentcard never sees the number). A vaulted card pays through the buy tool, where the user approves each purchase with Face ID on their device; it never becomes a card number you type, so after vault_started (or vault_ready, when a card is already in the vault) use buy for purchases instead of calling create_card again. If the user specifically needs a card NUMBER, that is an Agentcard funded from their cash balance, which requires KYC the first time: only after the user agrees, call create_card with source “issued”. Established users: the saved default decides (get_settings default_payment: their chosen added card, or the wallet balance); with no saved default, an active ADDED card wins, otherwise the cash balance. Per-call overrides: connected_card_id issues against a specific added card, source “issued” forces the cash balance, restart_setup mints a fresh vault link. If the balance is short on the issued path, top up with add_funds. Connections through a company OAuth client have NO card count or amount limits; only first-party personal accounts have per-plan caps. Call get_plan for the limits in effect.

Inputs

Field	Type	Description
`amount_cents` (required)	number	Card funding amount in CENTS, not dollars (minimum 100). 100 = $1.00 and 2500 = $25.00; a value like 25 would be $0.25. Company-governed connections have no maximum; personal accounts are capped by their plan — call get_plan for the limits in effect.
`connected_card_id`	string	Multi-card: issue against a SPECIFIC added card (an id from the user’s added cards, see list_added_cards) instead of the newest active one. Omit for the default.
`source`	string: `issued`	Force the card to be funded from the user’s cash balance (the issued path: KYC + wallet funding) even when they have an added or vaulted card or would otherwise be offered the vault. Use it only after the user explicitly picks the balance option. Omit for the default (an active added card wins; first-time users get the vault link).
`restart_setup`	boolean	Set true ONLY when the user lost or never received a vault link, it expired (about 15 minutes), or they want to add ANOTHER card. Never needed on the first call or for normal retries.
`funds_source`	string: `onramp_flow` · `company_flow`	Where the card funds come from. OMIT unless instructed: the server applies the right default (company-connected accounts use the company wallet automatically when the company enables it). company_flow = the company’s wallet funds the card; onramp_flow = the user’s own wallet.
`type`	string: `single_use` · `multi_use`	Card behavior. ‘single_use’ (default) closes after its first approved charge — right for one-off purchases. ‘multi_use’ stays open across charges until its total limit is spent — right for subscriptions and recurring merchants. Multi-use cards can be paused (pause_card), resumed (resume_card), and resized (update_card_limit).
`expires_at`	string	Optional hard expiry for a multi-use card (ISO-8601 with timezone, e.g. “2027-01-01T00:00:00Z”). Must be in the future, at most 365 days out. The card closes automatically when it passes.
`preset`	string · object	Rules for this card: a built-in name (ai_labs, weekday_meals, cli_only, daily), a comma-separated list of built-ins, a saved name or id from list_presets, inline JSON privileges, or `{ name?, privileges }`. Rules only tighten. Inline, a currency rule is `{ "kind": "currency", "currencies": ["USD"] }`, with `"enforcement": "watch"` for `Watch`. Omit it and the card inherits the app default, then the account default, else it is unrestricted. See Set rules on a card.
`scope_preset`	string: `ai_labs`	Older spelling of `preset: "ai_labs"`: a multi-use card for AI vendors (OpenAI, Anthropic, Gemini). The card network declines charges anywhere else. Charges at software and AI vendors on this card earn the boosted tokenback rate; other charges on it earn the normal rate. Requires type ‘multi_use’; with single_use the call is refused with `scope_preset_requires_multi_use`. Prefer `preset`.

Returns

Field	Type	Description
`message` (required)	string	Human-readable result or guidance for the next step.
`status`	string	Outcome discriminator: “created” (card issued), “vault_started” (first-time setup: send vaultUrl to the user; once their card is in the vault, purchases go through buy, not create_card), “vault_ready” (the user’s own card is already in their vault: use buy; only source “issued” produces a card number), “attach_started” / “attach_pending” (an older add-card enrollment still in flight: send attachUrl or wait, then call again with the same arguments), “issuing_suggested” (legacy servers only: offer the balance-funded fallback, noting it requires KYC, and only then call again with source “issued”), “approval_required” (human approval needed), “approval_pending” (added-card passkey approval: send approvalUrl to the user, then retry with the same arguments in ~10s), “kyc_required” (issued path only), “user_info_required” (check missingFields: phone/terms go through submit_user_info; consent must be recorded by the connecting platform), “beta_capacity_reached”, “issuing_balance_insufficient” (issued path only), “payment_method_declined”, “limit_reached”, “funding_in_progress” (company wallet funding underway: retry with the same arguments in ~10s), “funding_not_approved”, “org_wallet_funding_required”, “org_wallet_unavailable” (the company wallet backing this account is not active: the company must finish setup; do not retry immediately), or “rate_limited” (wait ~1 minute, then retry).
`cardId`	string	The new card ID. Present only when status is “created”.
`last4`	string	Last four digits of the new card. Present only when status is “created”.
`expiry`	string	Card expiry (MM/YY). Present only when status is “created”.
`balanceCents`	number	Card balance in cents. Present only when status is “created”.
`balanceDollars`	string	Card balance formatted as USD dollars, e.g. “12.50”. Present only when status is “created”.
`cardStatus`	string	Card status, e.g. “active”. Present only when status is “created”.
`preset`	object	The rules on the new card: `id`, `name`, `version`, `summary`. Null when the card is unrestricted. Present only when status is “created”.
`approvalId`	string	The approval request ID to pass to approve_request. Present only when status is “approval_required”.
`approvalUrl`	string	The passkey approval link to send to the user. Present only when status is “approval_pending”.
`vaultUrl`	string	The secure link the user opens to put their card in their vault. Present only when status is “vault_started”.
`vaultCards`	number	How many cards the user already holds in their vault. Present only when status is “vault_ready”.
`attachUrl`	string	The secure link the user opens to finish an older add-card enrollment. Present only when status is “attach_started”.
`expiresAt`	string	When the link expires (ISO 8601). Present when status is “vault_started” or “attach_started”.
`source`	string	”connected” when the card was created against the user’s added card. Absent for wallet-funded cards.
`reason`	string	On “issuing_suggested” (legacy servers only; current servers route every first-time user to the vault instead): why the card could not be added. On “kyc_required”: why the previous identity-verification attempt failed (e.g. “document_unverified_other”), present only when a prior attempt was rejected.
`missingFields`	array	What is missing when status is “user_info_required” (e.g. “termsAccepted”, “consent”).

Example call

{
  "tool": "create_card",
  "arguments": {
    "amount_cents": "\u2026"
  }
}

A card with a currency rule says who enforces it. create_card with "preset": { "privileges": [{ "kind": "currency", "currencies": ["USD", "EUR"] }] } on a sandbox connection, captured from a local run; structuredContent.preset.agentcardOnly lists currency:

TEST card created (sandbox connection).
Card ID: cmttouxtv000hjpk0bp7mbvzs
Last 4: 8549
Expiry: 09/28
Balance: $20.00
Status: OPEN
Preset: Currency: USD, EUR. (Agentcard enforces the currency rule at checkout and settlement; the card network does not)

This is a TEST card: no real charge, not usable at real merchants.
Tell the user it is a test card before they try to spend it.

Example error

scope_preset: "ai_labs" with type: "single_use", captured from a local sandbox. isError is set and structuredContent.status carries the code:

{
  "content": [
    {
      "type": "text",
      "text": "Scoped (AI) cards are always multi-use — omit type or pass multi_use."
    }
  ],
  "structuredContent": {
    "message": "Scoped (AI) cards are always multi-use — omit type or pass multi_use.",
    "status": "scope_preset_requires_multi_use"
  },
  "isError": true
}

A preset with a currency Agentcard cannot read answers the same way, with policy_invalid. create_card with "preset": { "privileges": [{ "kind": "currency", "currencies": ["ZZZ"] }] }, captured from a local run:

{
  "content": [
    {
      "type": "text",
      "text": "ZZZ is not a currency code. Use an ISO 4217 code (USD, EUR, GBP, JPY) or a common name (dollars, euros, pounds, yen)."
    }
  ],
  "structuredContent": {
    "message": "ZZZ is not a currency code. Use an ISO 4217 code (USD, EUR, GBP, JPY) or a common name (dollars, euros, pounds, yen).",
    "status": "policy_invalid"
  },
  "isError": true
}

MCP

Organization tools

User tools

What it does

Inputs

Returns

Example call

Example error

​What it does

​Inputs

​Returns

​Example call

​Example error

What it does

Inputs

Returns

Example call

Example error