> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useproxy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools Reference

> Complete documentation for all Proxy MCP tools

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

<ParamField path="email" type="string">
  Customer email address
</ParamField>

<ParamField path="firstName" type="string">
  Customer first name
</ParamField>

<ParamField path="lastName" type="string">
  Customer last name
</ParamField>

<ParamField path="type" type="string">
  Customer type: `consumer` or `corporate`
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "status": "approved",
  "reason": null,
  "kycVerified": true
}
```

***

## Agents

Tools for managing autonomous agents.

### agent.create

Create a new agent for the customer.

<ParamField path="name" type="string" required>
  Human-readable agent name
</ParamField>

<ParamField path="externalId" type="string">
  Your unique identifier for the agent
</ParamField>

<ParamField path="status" type="string">
  Initial status: `active`, `paused`, or `disabled`
</ParamField>

<ParamField path="limitAmount" type="number">
  Spending limit amount (in cents)
</ParamField>

<ParamField path="limitCurrency" type="string">
  Spending limit currency (default: `usd`)
</ParamField>

<ParamField path="policy" type="object">
  Policy overrides (see [Cards](/concepts/cards) for policy options)
</ParamField>

<ParamField path="metadata" type="object">
  Custom metadata key-value pairs
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "agentId": "agent_abc123",
  "name": "Shopping Assistant",
  "status": "active",
  "externalId": "my-agent-001"
}
```

***

### agent.list

List all agents for the customer.

<ParamField path="limit" type="number">
  Maximum results to return (default: 50)
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="agentId" type="string" required>
  Agent public ID
</ParamField>

<ParamField path="name" type="string">
  New agent name
</ParamField>

<ParamField path="externalId" type="string">
  New external identifier
</ParamField>

<ParamField path="limitAmount" type="number">
  New spending limit amount
</ParamField>

<ParamField path="limitCurrency" type="string">
  New spending limit currency
</ParamField>

<ParamField path="policy" type="object">
  Policy overrides
</ParamField>

<ParamField path="metadata" type="object">
  Custom metadata
</ParamField>

**Auth:** User only

***

### agent.pause

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

<ParamField path="agentId" type="string" required>
  Agent public ID
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "agentId": "agent_abc123",
  "status": "paused"
}
```

***

### agent.disable

Permanently disable an agent. Disabled agents cannot be reactivated.

<ParamField path="agentId" type="string" required>
  Agent public ID
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "agentId": "agent_abc123",
  "status": "disabled"
}
```

***

### agent.token.issue

Create a new authentication token for an agent.

<ParamField path="agentId" type="string" required>
  Agent public ID
</ParamField>

<ParamField path="name" type="string">
  Token name for identification
</ParamField>

**Auth:** User only

**Response:**

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

<Warning>
  The token value is only returned once. Store it securely immediately after creation.
</Warning>

***

### agent.token.revoke

Revoke an agent token, immediately invalidating it.

<ParamField path="tokenId" type="string" required>
  Token public ID
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "tokenId": "tok_abc123",
  "revoked": true
}
```

***

## Cards

Tools for managing virtual cards.

### card.create

Create a new virtual card. Requires completed KYC verification.

<ParamField path="agentId" type="string">
  Agent to assign the card to
</ParamField>

<ParamField path="displayName" type="string">
  Card display name (default: "Virtual Card")
</ParamField>

<ParamField path="usage" type="string">
  Card usage type: `single` (one-time) or `multi` (reusable)
</ParamField>

<ParamField path="limit" type="object">
  Spending limit configuration

  ```json theme={"system"}
  {
    "amount": 10000,
    "currency": "usd",
    "frequency": "monthly"
  }
  ```
</ParamField>

<ParamField path="policy" type="object">
  Policy overrides
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="limit" type="number">
  Maximum results to return (default: 50)
</ParamField>

**Auth:** Both (User or Agent)

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="cardId" type="string" required>
  Card public ID
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "cardId": "card_abc123",
  "status": "locked"
}
```

***

### card.unlock

Unlock a previously locked card.

<ParamField path="cardId" type="string" required>
  Card public ID
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "cardId": "card_abc123",
  "status": "active"
}
```

***

### card.cancel

Permanently cancel a card. This action cannot be undone.

<ParamField path="cardId" type="string" required>
  Card public ID
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "cardId": "card_abc123",
  "status": "canceled"
}
```

***

### card.policy.update

Update per-card policy overrides.

<ParamField path="cardId" type="string" required>
  Card public ID
</ParamField>

<ParamField path="policy" type="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
</ParamField>

<ParamField path="usage" type="string">
  Card usage type: `single` or `multi`
</ParamField>

<ParamField path="expiresAt" type="number">
  Card expiration timestamp (milliseconds)
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="cardId" type="string" required>
  Card public ID
</ParamField>

<ParamField path="summary" type="string" required>
  Description of the intended purchase
</ParamField>

<ParamField path="intentId" type="string">
  Client-provided intent ID for idempotency
</ParamField>

<ParamField path="expectedAmount" type="number">
  Expected transaction amount (in cents)
</ParamField>

<ParamField path="expectedCurrency" type="string">
  Expected currency (default: `usd`)
</ParamField>

<ParamField path="expectedMerchant" type="string">
  Expected merchant name
</ParamField>

<ParamField path="expectedMccs" type="array">
  Expected merchant category codes
</ParamField>

<ParamField path="toleranceAmount" type="number">
  Allowed amount variance (in cents)
</ParamField>

<ParamField path="tolerancePercent" type="number">
  Allowed percentage variance
</ParamField>

<ParamField path="ttlMinutes" type="number">
  Intent time-to-live in minutes
</ParamField>

<ParamField path="metadata" type="object">
  Custom metadata
</ParamField>

**Auth:** Agent only

**Response:**

```json theme={"system"}
{
  "intentId": "int_abc123",
  "clientIntentId": "my-intent-001",
  "status": "pending",
  "expiresAt": 1706749200000
}
```

***

### intent.list

List intents for the agent's cards.

<ParamField path="cardId" type="string">
  Filter by card ID
</ParamField>

<ParamField path="limit" type="number">
  Maximum results to return (default: 50)
</ParamField>

**Auth:** Agent only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="agentId" type="string">
  Configure for a specific agent
</ParamField>

<ParamField path="cardId" type="string">
  Configure for a specific card
</ParamField>

<ParamField path="requireApproval" type="boolean">
  Whether to require approval
</ParamField>

<ParamField path="autoApproveBelow" type="number">
  Auto-approve intents below this amount (cents)
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="cardId" type="string" required>
  Card public ID
</ParamField>

<ParamField path="intentRef" type="string">
  Intent public ID or client-provided ID
</ParamField>

<ParamField path="summary" type="string">
  Access request summary
</ParamField>

<ParamField path="expectedAmount" type="number">
  Expected amount (cents)
</ParamField>

<ParamField path="expectedCurrency" type="string">
  Expected currency
</ParamField>

<ParamField path="merchantText" type="string">
  Merchant name
</ParamField>

<ParamField path="reason" type="string">
  Reason for access
</ParamField>

<ParamField path="context" type="object">
  Client context
</ParamField>

**Auth:** Agent only

**Response (granted):**

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

**Response (denied):**

```json theme={"system"}
{
  "accessEventId": "acc_abc123",
  "status": "denied",
  "reasons": ["intent_required", "amount_exceeds_limit"]
}
```

<Warning>
  Card credentials are sensitive. The `card` object is only returned when access is granted and should be used immediately.
</Warning>

***

### access.events.list

List access events for the agent's cards.

<ParamField path="cardId" type="string">
  Filter by card ID
</ParamField>

<ParamField path="limit" type="number">
  Maximum results to return (default: 50)
</ParamField>

**Auth:** Agent only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="cardId" type="string">
  Filter by card ID
</ParamField>

<ParamField path="limit" type="number">
  Maximum results to return (default: 50)
</ParamField>

**Auth:** Both (User or Agent)

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="transactionId" type="string" required>
  Transaction public ID
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="transactionId" type="string" required>
  Transaction public ID
</ParamField>

<ParamField path="reason" type="string">
  Dispute reason (e.g., `unauthorized`, `duplicate`, `not_received`)
</ParamField>

<ParamField path="description" type="string">
  Detailed description of the dispute
</ParamField>

<ParamField path="metadata" type="object">
  Custom metadata
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "disputeId": "dsp_abc123",
  "transactionId": "txn_abc123",
  "status": "submitted",
  "reason": "unauthorized",
  "createdAt": 1706745600000
}
```

***

### dispute.list

List all disputes for the customer.

<ParamField path="limit" type="number">
  Maximum results to return (default: 50)
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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.

<ParamField path="disputeId" type="string" required>
  Dispute public ID
</ParamField>

<ParamField path="evidence" type="object">
  Evidence to add
</ParamField>

<ParamField path="description" type="string">
  Updated description
</ParamField>

<ParamField path="metadata" type="object">
  Custom metadata
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "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).

<ParamField path="limit" type="number">
  Maximum results to return (default: 50)
</ParamField>

**Auth:** User only

**Response:**

```json theme={"system"}
{
  "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:**

```json theme={"system"}
{
  "available": 95000,
  "held": 5000,
  "currency": "usd"
}
```

<Note>
  * `available`: Funds available for spending
  * `held`: Funds temporarily held for pending authorizations
  * All amounts are in cents
</Note>