Madhouse Wallet — MCP Server

Madhouse Wallet MCP Server

Send global payouts from any AI assistant using natural language.

The Madhouse Wallet MCP (Model Context Protocol) server connects AI assistants like Claude, Cursor, Copilot, and Windsurf to the Madhouse Wallet payout API — letting you send USDC payouts to 85+ currencies, manage bank recipients, and get live FX quotes entirely through chat.

⚡

Natural language

Just describe what you want. Your AI figures out which tool to call.

🌍

85+ currencies

Pay out to bank accounts across emerging and developed markets.

🔑

Your API key

Multi-tenant — each user provides their own Madhouse API key.

MCP Endpoint

https://main.d2sl38naixknlb.amplifyapp.com/api/mcp

Quick Start

Get up and running in under 2 minutes.

1
Get your API key
Log in to the Madhouse Wallet dashboard and navigate to Developers → API Keys to generate a key. It starts with mw_live_.
2
Add the MCP server to your AI client
Paste the endpoint URL and your API key as a Bearer token. See the Installation section for client-specific instructions.
3
Start sending in chat
Type something like “Send $500 to my recipient in Kenya” and your AI will handle the rest.

Authentication

Every request is authenticated with your Madhouse Wallet API key.

Pass your API key as a Bearer token in the Authorization header of every request. This is handled automatically by your AI client once you complete the setup.

HTTP Header

Authorization: Bearer mw_live_your_key

⚠

Keep your API key private. Never share it in public repositories, screenshots, or with untrusted parties. Each key is tied to your account and authorizes real money movement.

ℹ

The MCP server is multi-tenant — each user connects with their own key. There is no shared server-side secret.

Installation

Choose your AI client below for specific setup instructions.

Replace mw_live_your_key with your actual API key in all examples below.

Run this command in your terminal. Claude Code stores the config automatically.

Terminal

claude mcp add --transport http madhouse https://main.d2sl38naixknlb.amplifyapp.com/api/mcp \
  --header "Authorization: Bearer mw_live_your_key"

ℹ

Claude Code CLI is a separate tool from the Claude desktop app. Install it with npm install -g @anthropic-ai/claude-code.

Tools Reference

12 tools covering the full payout workflow — from quoting to recipient management.

Quotes & Limits

madhouse_get_limits

Returns the min and max USD amounts your account can send per transfer.

No parameters required.

Example prompt

“What are my Madhouse transfer limits?”

madhouse_get_quote

Get a live USD → target currency exchange rate. Returns a quoteId valid for 5 minutes required by create_transfer.

Parameters

Parameter	Type	Required	Description
source_amount	number	Yes	USD amount to send (e.g. 500)
target_currency	string	Yes	ISO 4217 code — e.g. "KES", "GBP", "EUR"

Example prompt

“Get me a quote to send $500 to Kenya.”

Transfers

madhouse_create_transfer

Initiate a USDC payout. Returns a deposit_address — send USDC there to trigger the bank transfer.

Parameters

Parameter	Type	Required	Description
quote_id	string (UUID)	Yes	From madhouse_get_quote — valid 5 min
amount	number	Yes	USD amount — must match the quote exactly
recipient_id	number	Yes	Recipient ID from madhouse_list_recipients
wallet_address	string	Yes	EVM (0x...) or Solana address sending USDC
user_id	string	Yes	Your Madhouse Wallet user ID (from account settings)
customer_uuid	string (UUID)	Yes	Your unique reference for this transfer
customer_email	string	No	Notification email (defaults to account email)
source_token	string	No	Token to send — default "usdc"
source_network	string	No	Network — default "base". Options: base, arbitrum, ethereum, optimism, polygon, solana

Example prompt

“Send $200 to John in Kenya using my Base wallet.”

madhouse_get_transfer

Poll the current status of a transfer. Status lifecycle: ready_to_process → processing → transfer_created → completed | failed.

Parameters

Parameter	Type	Required	Description
transfer_id	string	Yes	Transfer ID returned by madhouse_create_transfer

Example prompt

“What's the status of my transfer abc-123?”

madhouse_cancel_transfer

Cancel a pending transfer before USDC is sent. Omit transfer_id to cancel all pending transfers.

Parameters

Parameter	Type	Required	Description
transfer_id	string	No	Transfer ID to cancel. Omit to cancel ALL pending transfers.

Example prompt

“Cancel all my pending transfers.”

Recipients

madhouse_list_recipients

List all active bank recipients on your account.

No parameters required.

Example prompt

“Show me all my recipients.”

madhouse_get_recipient

Get details of a single recipient by ID.

Parameters

Parameter	Type	Required	Description
recipient_id	number	Yes	Recipient ID from madhouse_list_recipients

Example prompt

“Show details for recipient 12345.”

madhouse_create_recipient

Add a new bank account recipient. Call madhouse_get_account_requirements first to know which fields to provide.

Parameters

Parameter	Type	Required	Description
user_id	string	Yes	Your Madhouse Wallet user ID
currency	string	Yes	ISO 4217 code — e.g. "GBP", "KES"
type	string	Yes	Account type from madhouse_get_account_requirements — e.g. "sort_code", "iban"
account_holder_name	string	Yes	Full legal name of the account holder
details	object	Yes	Bank account fields — keys vary by currency/type

Example prompt

“Add a GBP recipient for Jane Smith with sort code 20-00-00 and account 12345678.”

madhouse_update_recipient

Update the name or bank details of an existing recipient.

Parameters

Parameter	Type	Required	Description
recipient_id	number	Yes	Recipient ID to update
account_holder_name	string	No	New full legal name
details	object	No	Updated bank account fields

Example prompt

“Update recipient 12345's name to Jane Doe.”

madhouse_delete_recipient

Permanently remove a bank recipient. Cannot delete while a transfer to them is in-flight.

Parameters

Parameter	Type	Required	Description
recipient_id	number	Yes	Recipient ID to delete

Example prompt

“Delete recipient 12345.”

Account Requirements

madhouse_get_account_requirements

Returns the bank fields required to create a recipient for a given currency — including validation rules and allowed values.

Parameters

Parameter	Type	Required	Description
currency	string	Yes	ISO 4217 code — e.g. "GBP", "NGN", "KES"

Example prompt

“What fields do I need to create a Nigerian Naira recipient?”

madhouse_refresh_account_requirements

Refresh required fields after filling in a field that triggers conditional requirements (e.g. selecting bank country reveals more fields).

Parameters

Parameter	Type	Required	Description
currency	string	Yes	ISO 4217 currency code
type	string	Yes	Account type — e.g. "iban", "sort_code"
details	object	Yes	Partial details filled in so far

Example prompt

“Refresh the requirements for an IBAN recipient after selecting Germany as the bank country.”

Examples

How your AI chains tools together to complete real payout workflows.

Check transfer limits

“What are my Madhouse transfer limits?”

Tool call sequence

1madhouse_get_limits → returns min/max USD amounts

Get an FX quote

“Get me a quote to send $500 to Kenya.”

Tool call sequence

1madhouse_get_limits → verify $500 is within limits
2madhouse_get_quote(500, "KES") → returns rate, fees, and quoteId

Send a payout end-to-end

“Send $200 to John in Kenya using my Base wallet.”

Tool call sequence

1madhouse_list_recipients → find John's recipient ID
2madhouse_get_quote(200, "KES") → get quoteId
3madhouse_create_transfer → returns deposit_address
→You send USDC to the deposit_address
5madhouse_get_transfer → poll until completed

Add a new recipient

“Add a UK GBP recipient for Jane Smith, sort code 20-00-00, account 12345678.”

Tool call sequence

1madhouse_get_account_requirements("GBP") → get required fields
2madhouse_create_recipient → creates the recipient

Supported Currencies

Pay out to 85+ currencies across emerging and developed markets.

AEDARSALLAUDBAMBDTBGNBHDBMDBOBBRLBWPCADCHFCLPCNYCOPCRCCVECZKDKKDOPEGPEURGBPGELGHSGMDGNFGTQHKDHNLHUFIDRILSINRISKJPYKESKGSKHRKRWKWDLAKLKRMADMNTMOPMURMXNMYRNADNGNNIONOKNPRNZDOMRPENPHPPKRPLNPYGQARRONRSDRWFSARSCRSEKSGDSRDTHBTNDTRYTZSUAHUGXUSDUYUVNDZAR

Use madhouse_get_account_requirements with any currency code to see what bank fields are required for that country.