# Nubank for Agents

This file is the quickest install and capability guide for agents and humans. If you are an AI agent, read this first, add the MCP server, complete OAuth with the user, then use the tools below.

## Install

MCP server URL:

```
https://new-mcp-demo.marciovm.com/mcp
```

If your MCP client accepts a remote server URL, add:

```json
{
  "mcpServers": {
    "nubank": {
      "url": "https://new-mcp-demo.marciovm.com/mcp"
    }
  }
}
```

If your client asks for scopes, request:

```
purchase_amount.read payments.pix.prepare payments.nupay.prepare approvals.read logs.read
```

OAuth is built in. Do not ask the user for an API key or password. The user approves access through the Nu mobile approval flow.

## What This MCP Server Can Do

This is a demo agentic payments surface. It lets an AI agent check the BRL amount available for purchase, prepare Pix and NuPay checkouts, read mobile approval status, and inspect fake demo audit logs.

Checkout tools prepare a Pix or NuPay approval request unless delegated authority applies. When approval is required, the user confirms in the mobile app and may choose Pix Financing instead of account balance for eligible purchases.

Delegated authority is user-controlled. The user can always require approval, or let an agent pay within per-transaction and daily limits that cannot exceed BRL 1,000.

Mobile approvals open under:

```
https://new-app-demo.marciovm.com
```

## Phone Approval QR Codes

The checkout tools can return an approval request for the user's phone. In the real product this is the moment the phone would receive a push notification. In this demo, make that obvious by showing the user a QR code to the phone approval page.

When a prepare tool returns an `approvalUrl` or `approvalId`, show the user a QR code to the phone approval page.

Rules for agents:

- If the tool response includes `approvalUrl`, encode that exact URL in the QR code.
- If the tool response only includes `approvalId`, build the URL as `https://new-app-demo.marciovm.com/approve/<approvalId>`.
- Show the plain approval link next to the QR code for fallback.
- Tell the user the action is staged and waiting for phone approval; do not say it is complete until `get_approval_status` returns `approved`.
- If the checkout returns `approved_by_delegated_authority`, no phone approval is waiting; explain that the user had already delegated authority within limits.

Example approval page:

```
https://new-app-demo.marciovm.com/approve/approval_0001
```

QR code payload: `https://new-app-demo.marciovm.com/approve/approval_0001`

Suggested message:

```
I prepared this action, but it still needs your phone approval. Scan this QR code or open https://new-app-demo.marciovm.com/approve/approval_0001, then I will check the approval status.
```

## Recommended Agent Flow

1. Add the MCP server at `https://new-mcp-demo.marciovm.com/mcp`.
2. Complete OAuth and ask for the minimum scopes needed.
3. Start with `get_available_purchase_amount` when you need to know whether the purchase can fit in the fake BRL purchase amount.
4. Prepare Pix or NuPay checkout only after the merchant, amount, checkout rail, and reason are clear to the user.
5. After a checkout tool returns an `approvalUrl` or `approvalId`, show a QR code to the phone approval page, then call `get_approval_status` until the user approves or declines.
6. Use `get_demo_audit_log` only when the user wants to inspect fake demo events for troubleshooting or narration.

## Tools

### get_available_purchase_amount

Read only the BRL amount available for agent-assisted purchase.

Input:

```json
{}
```

Use for:

- Checking whether a requested checkout fits within the fake purchase amount.
- Giving the user purchase readiness context without reading account activity.

### prepare_pix_checkout

Prepare a Pix checkout. The tool returns either a pending mobile approval request or an `approved_by_delegated_authority` payment result.

Input:

```json
{
  "merchant": "Town Shoes",
  "amount": "89.90",
  "pixKeyOrQrCode": "merchant Pix key or QR code",
  "reason": "Checkout for order #123"
}
```

Use for:

- Pix merchant checkout when the user provides a Pix key or QR payload.
- Showing the approval or delegated-authority path for a BRL payment.

### prepare_nupay_checkout

Prepare a NuPay checkout. The tool returns either a pending mobile approval request or an `approved_by_delegated_authority` payment result.

Input:

```json
{
  "merchant": "Town Shoes",
  "amount": "89.90",
  "checkoutUrl": "https://merchant.example/nupay/checkout",
  "reason": "Checkout for order #123"
}
```

Use for:

- NuPay merchant checkout when the user provides a NuPay checkout URL.
- Showing the approval or delegated-authority path for a BRL payment.

### get_approval_status

Read the state of a mobile approval.

Input:

```json
{
  "approvalId": "approval_0001"
}
```

Returns a pending, approved, declined, expired, or missing approval record.

### get_demo_audit_log

Read demo audit log entries.

Input:

```json
{}
```

Use for:

- Explaining what internal service calls would have happened.
- Demo narration and troubleshooting.

## Safety Rules For Agents

- Never claim real money moved. This is a fake-money demo.
- Never ask for credentials, card numbers, transaction history, or account history.
- Never ask the user for Nubank credentials, payment credentials, or API keys.
- Treat `prepare_pix_checkout` and `prepare_nupay_checkout` as approval requests unless the tool explicitly returns `approved_by_delegated_authority`.
- If `prepare_pix_checkout` or `prepare_nupay_checkout` returns `approvalUrl`, show the approval link or a QR code and wait for `get_approval_status`.
- If a checkout returns `approved_by_delegated_authority`, tell the user it was approved by their saved payment limits.
- Before preparing a checkout, repeat the merchant, exact BRL amount, rail, and reason in plain language.
- Do not fetch or infer account activity. The only account value this server can read is the amount available for purchase.
- If approval is declined, expired, or missing, stop and ask the user what to do next.
- Prefer the narrowest OAuth scopes that satisfy the user's request.

## Quick Copy Prompt

```
Connect my Nubank account to my AI agent. Use the MCP server at https://new-mcp-demo.marciovm.com/mcp. Request only the scopes needed for my task, and explain any action that needs Nu mobile approval before preparing it.
```