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

string

Customer first name

string

Customer last name

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.

string

required

Human-readable agent name

string

Your unique identifier for the agent

string

Initial status: active, paused, or disabled

number

Spending limit amount (in cents)

string

Spending limit currency (default: usd)

object

Policy overrides (see Cards for policy options)

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.

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.

string

required

Agent public ID

string

New agent name

string

New external identifier

number

New spending limit amount

string

New spending limit currency

object

Policy overrides

object

Custom metadata

Auth: User only

agent.pause

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

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.

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.

string

required

Agent public ID

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.

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.

string

Agent to assign the card to

string

Card display name (default: “Virtual Card”)

string

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

object

Spending limit configuration

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

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.

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.

string

required

Card public ID

Auth: User only Response:

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

card.unlock

Unlock a previously locked card.

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.

string

required

Card public ID

Auth: User only Response:

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

card.policy.update

Update per-card policy overrides.

string

required

Card public ID

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

string

Card usage type: single or multi

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.

string

required

Card public ID

string

required

Description of the intended purchase

string

Client-provided intent ID for idempotency

number

Expected transaction amount (in cents)

string

Expected currency (default: usd)

string

Expected merchant name

array

Expected merchant category codes

number

Allowed amount variance (in cents)

number

Allowed percentage variance

number

Intent time-to-live in minutes

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.

string

Filter by card ID

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.

string

Configure for a specific agent

string

Configure for a specific card

boolean

Whether to require approval

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.

string

required

Card public ID

string

Intent public ID or client-provided ID

string

Access request summary

number

Expected amount (cents)

string

Expected currency

string

Merchant name

string

Reason for access

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.

string

Filter by card ID

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.

string

Filter by card ID

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.

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.

string

required

Transaction public ID

string

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

string

Detailed description of the dispute

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.

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.

string

required

Dispute public ID

object

Evidence to add

string

Updated description

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).

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 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