> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lipafy.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lipafy.xyz/_mcp/server.

# Connect an agent

Add `https://api.lipafy.xyz/mcp` as a remote MCP server in your agent, then complete Lipafy OAuth when prompted. You can also use a scoped API credential for a server-side automation.

### Current Payment MCP Tool Catalogue

* **Autonomous Payments & Paybills**:
  * `lipafy_pay`: Autonomously execute an M-Pesa payment to a Till, PayBill, or beneficiary in a single turn if within workspace policy limits.
  * `lipafy_paybill`: Dedicated tool to pay Kenyan utilities (KPLC electricity tokens, Nairobi Water, KRA, eCitizen, Internet, Banks) with automated biller resolution.
  * `lipafy_search_paybills`: Search 100+ verified Kenyan Paybills, Tills, and required account reference formats.
* **Account & Identity**:
  * `lipafy_whoami`: Show the authenticated Lipafy account, credential type, and identity verification status.
  * `lipafy_get_wallet`: Get current available balance, pending holds, and currency.
* **Merchant Payment Collection (WhatsApp & Chat Commerce)**:
  * `lipafy_collect_payment`: Charge customers via on-device M-Pesa STK push directly inside WhatsApp, Telegram, or chat sales flows.
  * `lipafy_get_payment_status`: Verify customer payment settlement status before fulfilling orders.
* **Wallet Topups & Self-Funding (Interactive STK Push)**:
  * `lipafy_quote_topup_fee`, `lipafy_initiate_topup`, and `lipafy_get_topup`: Quote deposit fees and trigger an interactive on-device M-Pesa PIN prompt on the owner's phone.
* **Controlled Intent Workflow**:
  * `lipafy_quote_payout_fee`: Quote Lipafy fee and total wallet debit for external disbursements.
  * `lipafy_create_payment_intent`, `lipafy_list_payment_intents`, and `lipafy_get_payment_intent`: Prepare immutable payment intents.
  * `lipafy_list_approval_requests`: Inspect approval requests awaiting human review.
  * `lipafy_submit_payment_intent`: Submit an approved payment intent for telecom dispatch.
  * `lipafy_cancel_payment_intent`: Cancel an uncompleted intent and immediately release the wallet ledger hold.
* **Beneficiaries & Masked Destinations**:
  * `lipafy_list_beneficiaries` and `lipafy_create_beneficiary`: Manage workspace destinations (PayBill, Till, M-Pesa phone, PesaLink bank).
* **Internal Wallet-to-Wallet Transfers**:
  * `lipafy_resolve_internal_recipient`, `lipafy_quote_internal_transfer`, `lipafy_confirm_internal_transfer`, `lipafy_list_internal_transfers`, and `lipafy_get_internal_transfer`.
* **Withdrawals & History**:
  * `lipafy_create_withdrawal`: Withdraw wallet funds to an M-Pesa phone number (flat KES 100 fee).
  * `lipafy_list_wallet_transactions` and `lipafy_get_wallet_transaction`: Inspect append-only ledger entries.

### Autonomous Mode & Safety Controls

Agent credentials inherit server-enforced workspace policies configured under **Controls** (`/controls`):

1. **Approval Threshold**: If an autonomous payment (`lipafy_pay` or `lipafy_paybill`) is within the approved threshold (e.g. $\le$ KES 1,000), it executes straight-through to M-Pesa in a single turn and returns the M-Pesa tracking ID and transaction receipt.
2. **Human Review Escalation**: If the payment exceeds the autonomous threshold or daily budget, Lipafy halts execution, places the exact funds on ledger hold, and returns a human approval URL (`https://app.lipafy.xyz/approvals`).
3. **Identity Verification**: Before executing external payments, the account owner must complete identity verification. If unverified, tools return an actionable link to complete KYC.
4. **Idempotency Guarantee**: Every payment uses a unique `idempotency_key` preventing duplicate debits on retries.

Machine-readable operating instructions are available at `https://lipafy.xyz/agent.txt`.