# Bipa — Full Integration Guide

> Payments for AI agents. Your agent pays. You approve with biometrics.

Bipa gives AI agents purchasing power over PIX (Brazil's instant payment network).
Every transaction requires human approval via biometrics in the Bipa mobile app.

---

## MCP Server

- **Remote URL**: `https://mcp.bipa.app/mcp`
- **Local command**: `bipa mcp serve --stdio`
- **Transport**: Streamable HTTP (remote) or stdio (local)
- **Auth (remote)**: OAuth 2.1 with PKCE, discovery at `/.well-known/oauth-authorization-server`
- **Auth (local)**: Run `bipa login` to authenticate via browser

---

## MCP Tools Reference

### bipa_balance
Read available balance in cents.
- Inputs: none
- Returns: `{ "available_cents": 987650 }`

### bipa_pix_pay_key
Send a PIX payment by Pix key. Returns immediately — does NOT wait for user approval. Prefer `bipa_pix_recipient_suggestions` → `bipa_pix_pay_recipient` when the user asks to pay someone by name.
- Inputs:
  - `key` (string, required) — PIX key of the recipient (email, phone, CPF, CNPJ, or EVP)
  - `amount_cents` (integer, required) — Amount in cents (must be > 0)
  - `agent_message` (string, required) — Agent explanation shown to the user during payment approval
  - `note` (string, optional) — Payment description
- Returns: `{ "status": "awaiting_approval", "key": "...", "owner_name": "...", "amount_brl": "R$ 145,00", "message": "Payment submitted. The user must approve this operation in the Bipa app. Use bipa_history to check the transaction status." }`
- Statuses: `awaiting_approval`, `scheduled`
- **Important**: After calling pay, tell the user to approve in the Bipa app. Use `bipa_history` to check whether the payment was completed.

### bipa_pix_recipient_suggestions
List the user's top 10 most frequent/recent PIX payment recipients. Call this FIRST when the user wants to pay someone by name.
- Inputs: none
- Returns: `{ "recipients": [{ "id": "42", "name": "João", "bank_name": "Nubank", "document": "•••.456.789-••", "document_kind": "cpf", "is_trusted_contact": false, "branch": "0001", "account": "12345-6" }] }`
- **Next step**: Use recipient `id` as `pix_payment_recipient_id` in `bipa_pix_pay_recipient`.

### bipa_pix_pay_recipient
Pay a saved recipient by their id (from `bipa_pix_recipient_suggestions`). Skips Pix key lookup.
- Inputs:
  - `pix_payment_recipient_id` (integer, required) — Recipient id from `bipa_pix_recipient_suggestions`
  - `amount_cents` (integer, required) — Amount in cents (must be > 0)
  - `agent_message` (string, required) — Agent explanation shown to the user during payment approval
  - `note` (string, optional) — Payment description
- Returns: same as `bipa_pix_pay_key`

### bipa_history
List recent transactions or get details by ID.
- Inputs:
  - `id` (string, optional) — Transaction ID for details. Omit for list.
  - `limit` (integer, optional) — Number of recent transactions to return when listing (default 20, max 50)
- Returns (list): `{ "transactions": [{ "transaction_id": "...", "title": "...", "direction": "credit|debit", "amount_cents": 1250, "amount_formatted": "+R$ 12,50", "status": "...", "timestamp": "..." }] }`
- Returns (detail): `{ "transaction_id": "...", "title": "...", "direction": "...", "amount_cents": ..., "amount_formatted": "...", "status": "...", "note": "...", "created_at": "...", "updated_at": "..." }`

### bipa_pix_brcode_decode
Decode a PIX BR Code / Copia e Cola payload.
- Inputs:
  - `code` (string, required) — Raw BR Code payload
- Returns: `{ "raw": "...", "field_count": 3, "fields": [{ "tag": "00", "value": "01" }] }`

### bipa_deposit
List your PIX deposit keys for receiving payments.
- Inputs: none
- Returns: `{ "keys": [{ "key": "...", "key_type": "evp|cpf_claimed|email_owned|..." }] }`

### bipa_pix_keys
CLI-parity alias for listing configured PIX keys.
- Inputs: none
- Returns: `{ "keys": [{ "key": "...", "key_type": "evp|cpf_claimed|email_owned|..." }] }`

### bipa_limits
Read transfer risk limits.
- Inputs: none
- Returns: `{ "daily_limit_cents": 2000000, "nightly_limit_cents": 2000000, ... }`

### bipa_account
Read account profile and metadata.
- Inputs: none
- Returns: `{ "user_id": "...", "owner_name": "...", "document": "...", "status": "active", "stark_pix_keys": [...] }`

### bipa_whoami
Show current session status.
- Inputs: none
- Returns: `{ "has_session": true, "agent_name": "..." }`

---

## Integration by Platform

### Claude Desktop (local + remote)

Local — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "bipa": {
      "command": "bipa",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}
```

Remote — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "bipa": {
      "url": "https://mcp.bipa.app/mcp"
    }
  }
}
```

### Claude.ai (remote only)
Settings → Connectors → Add Connector → enter `https://mcp.bipa.app/mcp` → complete OAuth.

### Claude Code (local + remote)
```bash
# Local
claude mcp add bipa -- bipa mcp serve --stdio

# Remote
claude mcp add --transport http bipa https://mcp.bipa.app/mcp
```

### Cursor (local + remote)

Local — `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "bipa": {
      "command": "bipa",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}
```

Remote — `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "bipa": {
      "url": "https://mcp.bipa.app/mcp"
    }
  }
}
```

### ChatGPT (remote only)
Settings → Apps & Connectors → Advanced → enable Developer Mode → Create → enter name "Bipa", URL `https://mcp.bipa.app/mcp`, Auth: OAuth → Create → authorize with Bipa.

### VS Code / GitHub Copilot (local + remote)

Local — `.vscode/mcp.json`:
```json
{
  "servers": {
    "bipa": {
      "type": "stdio",
      "command": "bipa",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}
```

Remote — `.vscode/mcp.json`:
```json
{
  "servers": {
    "bipa": {
      "type": "http",
      "url": "https://mcp.bipa.app/mcp"
    }
  }
}
```
Requires `chat.mcp.enabled: true` in settings. Tools available in Copilot Agent mode.

### Windsurf (local only)

`~/.codeium/windsurf/mcp_config.json`:
```json
{
  "mcpServers": {
    "bipa": {
      "command": "bipa",
      "args": ["mcp", "serve", "--stdio"]
    }
  }
}
```

---

## Prerequisites

1. A **Bipa account** with approved registration
2. For local mode, prefer the managed installer: `curl -fsSL https://agents.bipa.app/install.sh | sh`, then run `bipa login`
3. Developer-only package-manager installs are also available in the main docs, but agents should prefer the managed installer
4. For remote mode: no installation needed — the MCP client handles OAuth automatically

## How Authentication Works

- **Local**: The CLI opens your browser for Bipa login. Session token is stored at `~/.bipa/credentials.json`.
- **Remote**: The MCP client discovers OAuth endpoints at `/.well-known/oauth-authorization-server`, redirects to Bipa for authorization, and exchanges the code for an access token using PKCE. Tokens are refreshed automatically.