MCP Tools Reference

The Proxy MCP server provides 29 tools organized into logical categories. Each tool has specific authentication requirements and parameters.

Authentication Requirements

Tools are restricted based on authentication type:

Auth Type	Description
User	Requires Clerk JWT token (OAuth flow)
Agent	Requires agent token (`agt_xxx`)
Both	Accessible by either user or agent

Onboarding

Tools for initializing customer accounts.

onboarding.start

Create or link a customer account and return KYC status.

string

Customer email address

firstName

string

Customer first name

lastName

string

Customer last name

type

string

Customer type: consumer or corporate

Auth: User only Response:

{
  "customerId": "cust_abc123",
  "status": "created",
  "kycStatus": "not_started",
  "completionLink": null
}

onboarding.status

Fetch the current onboarding and KYC status. Auth: User only Parameters: None Response:

{
  "customerId": "cust_abc123",
  "type": "consumer",
  "status": "approved",
  "kycStatus": "verified",
  "completionLink": null,
  "rainUserId": "usr_xxx"
}

KYC

Tools for identity verification.

kyc.link

Return a hosted KYC verification link for the current user. Auth: User only Parameters: None Response:

{
  "url": "https://verify.raincards.xyz/...",
  "status": "initiated",
  "message": "Complete verification at the provided URL."
}

kyc.status

Return the current KYC verification status. Auth: User only Parameters: None Response:

{
  "status": "approved",
  "reason": null,
  "kycVerified": true
}

Agents

Tools for managing autonomous agents.

agent.create

Create a new agent for the customer.

name

string

required

Human-readable agent name

externalId

string

Your unique identifier for the agent

status

string

Initial status: active, paused, or disabled

limitAmount

number

Spending limit amount (in cents)

limitCurrency

string

Spending limit currency (default: usd)

policy

object

Policy overrides (see Cards for policy options)

metadata

object

Custom metadata key-value pairs

Auth: User only Response:

{
  "agentId": "agent_abc123",
  "name": "Shopping Assistant",
  "status": "active",
  "externalId": "my-agent-001"
}

agent.list

List all agents for the customer.

limit

number

Maximum results to return (default: 50)

Auth: User only Response:

{
  "agents": [
    {
      "agentId": "agent_abc123",
      "name": "Shopping Assistant",
      "status": "active",
      "externalId": "my-agent-001",
      "createdAt": 1706745600000
    }
  ],
  "hasMore": false
}

agent.update

Update agent metadata, limits, or policy.

agentId

string

required

Agent public ID

name

string

New agent name

externalId

string

New external identifier

limitAmount

number

New spending limit amount

limitCurrency

string

New spending limit currency

policy

object

Policy overrides

metadata

object

Custom metadata

Auth: User only

agent.pause

Temporarily pause an agent. Paused agents cannot access cards or make purchases.

agentId

string

required

Agent public ID

Auth: User only Response:

{
  "agentId": "agent_abc123",
  "status": "paused"
}

agent.disable

Permanently disable an agent. Disabled agents cannot be reactivated.

agentId

string

required

Agent public ID

Auth: User only Response:

{
  "agentId": "agent_abc123",
  "status": "disabled"
}

agent.token.issue

Create a new authentication token for an agent.

agentId

string

required

Agent public ID

name

string

Token name for identification

Auth: User only Response:

{
  "tokenId": "tok_abc123",
  "token": "agt_xxxxxxxxxxxxxxxxxxxx",
  "warning": "Store this token securely. It will not be shown again."
}

The token value is only returned once. Store it securely immediately after creation.

agent.token.revoke

Revoke an agent token, immediately invalidating it.

tokenId

string

required

Token public ID

Auth: User only Response:

{
  "tokenId": "tok_abc123",
  "revoked": true
}

Cards

Tools for managing virtual cards.

card.create

Create a new virtual card. Requires completed KYC verification.

agentId

string

Agent to assign the card to

displayName

string

Card display name (default: “Virtual Card”)

usage

string

Card usage type: single (one-time) or multi (reusable)

limit

object

Spending limit configuration

{
  "amount": 10000,
  "currency": "usd",
  "frequency": "monthly"
}

policy

object

Policy overrides

Auth: User only Response:

{
  "cardId": "card_abc123",
  "displayName": "Shopping Card",
  "status": "active",
  "last4": "4242",
  "agentId": "agent_abc123"
}

card.list

List cards. Scoped to assigned cards when using agent authentication.

limit

number

Maximum results to return (default: 50)

Auth: Both (User or Agent) Response:

{
  "cards": [
    {
      "cardId": "card_abc123",
      "displayName": "Shopping Card",
      "status": "active",
      "last4": "4242",
      "usage": "multi",
      "createdAt": 1706745600000
    }
  ],
  "hasMore": false
}

card.lock

Temporarily lock a card, preventing all transactions.

cardId

string

required

Card public ID

Auth: User only Response:

{
  "cardId": "card_abc123",
  "status": "locked"
}

card.unlock

Unlock a previously locked card.

cardId

string

required

Card public ID

Auth: User only Response:

{
  "cardId": "card_abc123",
  "status": "active"
}

card.cancel

Permanently cancel a card. This action cannot be undone.

cardId

string

required

Card public ID

Auth: User only Response:

{
  "cardId": "card_abc123",
  "status": "canceled"
}

card.policy.update

Update per-card policy overrides.

cardId

string

required

Card public ID

policy

object

Policy configuration. Available options:

requireIntent: Require intent declaration before access
requireApproval: Require explicit approval for intents
autoApproveBelow: Auto-approve intents below this amount (cents)
allowedMccs: Array of allowed merchant category codes
blockedMccs: Array of blocked merchant category codes
limits: Per-auth, daily, or monthly limits

usage

string

Card usage type: single or multi

expiresAt

number

Card expiration timestamp (milliseconds)

Auth: User only Response:

{
  "cardId": "card_abc123",
  "policy": {
    "requireIntent": true,
    "autoApproveBelow": 5000
  },
  "usage": "multi",
  "expiresAt": null
}

Intents

Tools for declaring spending intents. Agent authentication only.

intent.create

Create a new spending intent before making a purchase.

cardId

string

required

Card public ID

summary

string

required

Description of the intended purchase

intentId

string

Client-provided intent ID for idempotency

expectedAmount

number

Expected transaction amount (in cents)

expectedCurrency

string

Expected currency (default: usd)

expectedMerchant

string

Expected merchant name

expectedMccs

array

Expected merchant category codes

toleranceAmount

number

Allowed amount variance (in cents)

tolerancePercent

number

Allowed percentage variance

ttlMinutes

number

Intent time-to-live in minutes

metadata

object

Custom metadata

Auth: Agent only Response:

{
  "intentId": "int_abc123",
  "clientIntentId": "my-intent-001",
  "status": "pending",
  "expiresAt": 1706749200000
}

intent.list

List intents for the agent’s cards.

cardId

string

Filter by card ID

limit

number

Maximum results to return (default: 50)

Auth: Agent only Response:

{
  "intents": [
    {
      "intentId": "int_abc123",
      "clientIntentId": "my-intent-001",
      "cardId": "card_abc123",
      "status": "pending",
      "summary": "Purchase development tools",
      "expectedAmount": 9900,
      "expiresAt": 1706749200000,
      "createdAt": 1706745600000
    }
  ]
}

intent.autoApprove.configure

Configure auto-approval thresholds at the customer, agent, or card level.

agentId

string

Configure for a specific agent

cardId

string

Configure for a specific card

requireApproval

boolean

Whether to require approval

autoApproveBelow

number

Auto-approve intents below this amount (cents)

Auth: User only Response:

{
  "agentId": "agent_abc123",
  "requireApproval": true,
  "autoApproveBelow": 5000
}

Access

Tools for requesting card credentials. Agent authentication only.

access.request

Request access to card credentials for an approved intent.

cardId

string

required

Card public ID

intentRef

string

Intent public ID or client-provided ID

summary

string

Access request summary

expectedAmount

number

Expected amount (cents)

expectedCurrency

string

Expected currency

merchantText

string

Merchant name

reason

string

Reason for access

context

object

Client context

Auth: Agent only Response (granted):

{
  "accessEventId": "acc_abc123",
  "status": "granted",
  "expiresAt": 1706746200000,
  "card": {
    "pan": "4111111111114242",
    "cvc": "123",
    "expiryMonth": "12",
    "expiryYear": "2027"
  }
}

Response (denied):

{
  "accessEventId": "acc_abc123",
  "status": "denied",
  "reasons": ["intent_required", "amount_exceeds_limit"]
}

Card credentials are sensitive. The card object is only returned when access is granted and should be used immediately.

access.events.list

List access events for the agent’s cards.

cardId

string

Filter by card ID

limit

number

Maximum results to return (default: 50)

Auth: Agent only Response:

{
  "events": [
    {
      "accessEventId": "acc_abc123",
      "cardId": "card_abc123",
      "status": "granted",
      "summary": "Purchase development tools",
      "expectedAmount": 9900,
      "grantedAt": 1706745600000,
      "expiresAt": 1706746200000,
      "consumedAt": 1706745700000,
      "createdAt": 1706745600000
    }
  ]
}

Transactions

Tools for viewing transaction history.

transaction.list

List transactions. Scoped to agent’s cards when using agent authentication.

cardId

string

Filter by card ID

limit

number

Maximum results to return (default: 50)

Auth: Both (User or Agent) Response:

{
  "transactions": [
    {
      "transactionId": "txn_abc123",
      "type": "authorization",
      "status": "completed",
      "amount": 9900,
      "currency": "usd",
      "merchant": {
        "name": "GitHub Inc",
        "mcc": "5734",
        "city": "San Francisco",
        "country": "US"
      },
      "createdAt": 1706745600000
    }
  ],
  "hasMore": false
}

transaction.get

Fetch details of a single transaction.

transactionId

string

required

Transaction public ID

Auth: User only Response:

{
  "transactionId": "txn_abc123",
  "type": "authorization",
  "status": "completed",
  "amount": 9900,
  "currency": "usd",
  "merchant": {
    "name": "GitHub Inc",
    "mcc": "5734",
    "city": "San Francisco",
    "country": "US"
  },
  "cardId": "card_abc123",
  "memo": null,
  "createdAt": 1706745600000,
  "settledAt": 1706832000000
}

Disputes

Tools for managing transaction disputes.

dispute.create

File a dispute for a transaction.

transactionId

string

required

Transaction public ID

reason

string

Dispute reason (e.g., unauthorized, duplicate, not_received)

description

string

Detailed description of the dispute

metadata

object

Custom metadata

Auth: User only Response:

{
  "disputeId": "dsp_abc123",
  "transactionId": "txn_abc123",
  "status": "submitted",
  "reason": "unauthorized",
  "createdAt": 1706745600000
}

dispute.list

List all disputes for the customer.

limit

number

Maximum results to return (default: 50)

Auth: User only Response:

{
  "disputes": [
    {
      "disputeId": "dsp_abc123",
      "status": "under_review",
      "reason": "unauthorized",
      "amount": 9900,
      "currency": "usd",
      "createdAt": 1706745600000,
      "resolvedAt": null
    }
  ]
}

dispute.update

Update a dispute with additional evidence or information.

disputeId

string

required

Dispute public ID

evidence

object

Evidence to add

description

string

Updated description

metadata

object

Custom metadata

Auth: User only Response:

{
  "disputeId": "dsp_abc123",
  "status": "under_review",
  "updatedAt": 1706832000000
}

Funding

Tools for managing account funding.

funding.instructions.get

Get deposit instructions for funding the account. Auth: User only Parameters: None Response:

{
  "method": "crypto",
  "currency": "USDC",
  "network": "ethereum",
  "depositAddress": "0x1234567890abcdef...",
  "minDeposit": 100,
  "instructions": "Send USDC to the deposit address. Funds typically arrive within 10-30 minutes."
}

funding.history.list

List funding events (deposits, withdrawals, transfers).

limit

number

Maximum results to return (default: 50)

Auth: User only Response:

{
  "events": [
    {
      "transactionId": "txn_abc123",
      "type": "deposit",
      "amount": 100000,
      "currency": "usd",
      "status": "completed",
      "createdAt": 1706745600000,
      "completedAt": 1706746800000
    }
  ],
  "hasMore": false
}

Balance

Tools for checking account balance.

balance.get

Get the current available balance. Auth: Both (User or Agent) Parameters: None Response:

{
  "available": 95000,
  "held": 5000,
  "currency": "usd"
}

available: Funds available for spending
held: Funds temporarily held for pending authorizations
All amounts are in cents

MCP Server

​MCP Tools Reference

​Authentication Requirements

​Onboarding

​onboarding.start

​onboarding.status

​KYC

​kyc.link

​kyc.status

​Agents

​agent.create

​agent.list

​agent.update

​agent.pause

​agent.disable

​agent.token.issue

​agent.token.revoke

​Cards

​card.create

​card.list

​card.lock

​card.unlock

​card.cancel

​card.policy.update

​Intents

​intent.create

​intent.list

​intent.autoApprove.configure

​Access

​access.request

​access.events.list

​Transactions

​transaction.list

​transaction.get

​Disputes

​dispute.create

​dispute.list

​dispute.update

​Funding

​funding.instructions.get

​funding.history.list

​Balance

​balance.get

MCP Tools Reference

Authentication Requirements

Onboarding

onboarding.start

onboarding.status

KYC

kyc.link

kyc.status

Agents

agent.create

agent.list

agent.update

agent.pause

agent.disable

agent.token.issue

agent.token.revoke

Cards

card.create

card.list

card.lock

card.unlock

card.cancel

card.policy.update

Intents

intent.create

intent.list

intent.autoApprove.configure

Access

access.request

access.events.list

Transactions

transaction.list

transaction.get

Disputes

dispute.create

dispute.list

dispute.update

Funding

funding.instructions.get

funding.history.list

Balance

balance.get