amrood-mcp 0.3.1

MCP server for Amrood — give your AI agent a KYC-verified INR wallet

amrood-mcp

MCP server for Amrood — payment infrastructure for AI agents in India.

Give your AI agent a KYC-verified wallet. Agents can hold INR, pay other agents, hold funds in escrow, and settle to their owner's bank account — all through MCP tools.

Quick Start

With an existing agent key

{
  "mcpServers": {
    "amrood": {
      "command": "uvx",
      "args": ["amrood-mcp"],
      "env": {
        "AMROOD_AGENT_KEY": "agk_live_xxx"
      }
    }
  }
}

Fresh onboarding (no key yet)

{
  "mcpServers": {
    "amrood": {
      "command": "uvx",
      "args": ["amrood-mcp"]
    }
  }
}

Then ask your AI assistant to "register me on Amrood" and follow the OTP flow.

How Money Works

Funding an Agent

An agent's owner adds funds through a Cashfree payment link (UPI, card, or netbanking). The agent calls amrood_fund to generate a payment link, the human completes the payment, and the agent's balance is credited automatically.

Owner opens payment link → pays via UPI/card
  → Cashfree PG processes the payment
    → Agent's wallet balance is credited

Funds are held in a Cashfree Easy Split escrow account linked to the owner's PAN-verified identity. Amrood is non-custodial — it never holds the money directly.

Agent-to-Agent Payments

Agents pay each other instantly using amrood_pay. Specify the recipient by handle (e.g. researchbot) or agent ID. A 0.5% fee (minimum ₹1) is deducted from the sender.

Agent A calls amrood_pay(to="agentb", amount=100)
  → ₹100 credited to Agent B's balance
  → ₹1 fee deducted from Agent A
  → Both balances update instantly

Same-owner transfers (two agents owned by the same person) are ledger-only — no external payment gateway calls, instant settlement.

Escrow

For conditional payments, agents can hold funds in escrow before releasing them:

• Basic hold — funds held until explicitly released or refunded
• Timed hold — auto-refunds if not released within a deadline
• Attested hold — requires a third-party agent to approve before release

Agent A holds ₹500 in escrow
  → Agent B completes the work
    → Agent A releases escrow to Agent B
      → ₹500 credited to Agent B

Withdrawals

Owners can withdraw funds from an agent's wallet to their verified bank account using amrood_withdraw. Withdrawals update the agent's ledger balance immediately.

Agent calls amrood_withdraw(amount=500)
  → Agent balance reduced by ₹500
  → Funds marked for settlement to owner's bank

Settlement (How Money Reaches Your Bank)

Amrood uses Cashfree Easy Split for all fund management. Here's how settlement works:

• Schedule: All vendor balances are settled on a T+2 basis (2 business days after the transaction, at 11:00 AM).
• Auto-settlement: Cashfree automatically transfers the vendor's unsettled balance to the owner's linked bank account.
• On settlement, agent balances are zeroed out: When funds are settled to the bank, all agent wallets under that owner reset to ₹0. A settlement transaction is recorded for each agent.
• Notification: The owner receives an SMS and WhatsApp notification listing which agents were affected and how much was settled.

Day 0: Agent funded with ₹1,000
Day 0: Agent pays ₹200 to another agent, withdraws ₹300
        → Agent balance: ₹499 (after ₹1 fee)
Day 2: Cashfree auto-settles full vendor balance to owner's bank
        → Agent balance resets to ₹0
        → Owner receives SMS: "₹X settled to your HDFC account"
        → Owner re-funds agents as needed

Why zeroing out? Withdrawals and same-owner transfers are ledger-only operations — they reduce the agent's balance in Amrood but don't move money out of Cashfree's escrow. When Cashfree settles the full escrow balance to the bank, any remaining agent balance would be unbacked. Zeroing out keeps the ledger honest.

Spend Policies

Owners can configure guardrails on each agent:

• Daily spend limit — max amount the agent can spend per day
• Per-transaction limit — max amount per single payment
• Allowed payees — restrict which agents can receive payments

Available Tools

Onboarding (create an account via MCP)

Tool	Description
amrood_register	Start signup — sends OTP to a 10-digit Indian phone number
amrood_verify	Verify the OTP code and create/login the account
amrood_kyc	Submit KYC — PAN card + bank account or UPI ID
amrood_create_agent	Create an agent with a unique handle, returns the API key

Wallet & Payments

Tool	Description
amrood_balance	Check wallet balance, total funded, total spent
amrood_pay	Pay another agent by handle or ID
amrood_fund	Generate a payment link to add funds
amrood_withdraw	Withdraw funds to owner's bank account
amrood_transactions	View transaction history with filters

Escrow

Tool	Description
amrood_escrow_hold	Hold funds in escrow (basic, timed, or attested)
amrood_escrow_release	Release escrowed funds to a recipient
amrood_escrow_refund	Refund escrowed funds to sender
amrood_escrow_status	Check escrow status

Identity & Verification

Tool	Description
amrood_identity	View own handle, name, and status
amrood_proof	Generate a platform-signed proof of network membership
amrood_verify_agent	Check if an agent exists on the network
amrood_status	Check auth status and connectivity

Environment Variables

Variable	Required	Description
AMROOD_AGENT_KEY	No	Agent API key (skips onboarding if provided)
AMROOD_AGENT_ID	No	Agent ID (auto-resolved from key if not set)
AMROOD_BASE_URL	No	API base URL (default: https://amrood.io)

Key Concepts

Term	Meaning
Owner	A PAN-verified human who owns one or more agents
Agent	A programmable payment identity with its own wallet and API key
Handle	A unique username for an agent (e.g. researchbot) — used for payments and discovery
Vendor	The Cashfree Easy Split entity linked to an owner's bank account
Settlement	The process of Cashfree transferring escrowed funds to the owner's bank (T+2)
Escrow	Funds held conditionally — released on approval, refunded on timeout or dispute

Example: Full Agent Lifecycle

1. "Register me on Amrood"           → amrood_register (sends OTP)
2. "My code is 123456"               → amrood_verify (creates account)
3. "My PAN is ABCDE1234F, bank ..."  → amrood_kyc (verifies identity)
4. "Create an agent called ResBot"   → amrood_create_agent (returns API key)
5. "Fund my agent with ₹500"         → amrood_fund (returns payment link)
6. [Owner pays via UPI]              → balance credited automatically
7. "Pay @translator ₹50"             → amrood_pay (instant transfer)
8. "Hold ₹200 in escrow"             → amrood_escrow_hold
9. "Release escrow to @writer"       → amrood_escrow_release
10. "Withdraw ₹100"                  → amrood_withdraw (settles to bank at T+2)

Development

cd mcp
pip install -e .
amrood-mcp

Links

• Amrood Website
• API Documentation
• GitHub