@mrmonei/mcp-server

MCP server for the Monei API. Gives any AI agent access to wallets, transfers, crypto sends, swaps, offramp, and bill payments through natural language.

Works with Claude Desktop, Cursor, and any MCP compatible agent platform.

Quick start

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "monei": {
      "command": "npx",
      "args": ["-y", "@mrmonei/mcp-server"],
      "env": {
        "MONEI_API_KEY": "your_api_key_here",
      }
    }
  }
}

Restart Claude Desktop. You should see the Monei tools available in the tools menu.

Cursor (local)

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "monei": {
      "command": "npx",
      "args": ["-y", "@mrmonei/mcp-server"],
      "env": {
        "MONEI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor (remote via Railway)

{
  "mcpServers": {
    "monei": {
      "url": "https://mcp.monei.cc/sse",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Related MCP server: AgentPay

Environment variables

Transport modes

In http and sse modes the server is stateless and multi-user. Each client passes their own API key via Authorization: Bearer <key>. One deployed server serves many users.

Tool reference

Account

monei_get_account

Returns the authenticated user's profile.

Inputs: none

Returns:

{
  "id": "string",
  "email": "string",
  "firstName": "string",
  "lastName": "string",
  "phone": "string"
}

Example prompt: "Who am I logged in as?"

Wallet

monei_get_wallet

Returns NGN balance and all subwallets.

Inputs: none

Returns:

{
  "ngnBalance": "number",
  "subWallets": [{ "id": "string", "type": "string", "balance": "number" }]
}

Example prompt: "What's my wallet balance?"

monei_get_evm_portfolio

Returns the full token portfolio for an EVM chain including USD values.

Inputs:

Example prompt: "What tokens do I have on Base?"

monei_get_solana_portfolio

Returns SOL and all SPL token balances with USD values.

Inputs: none

Example prompt: "Show my Solana wallet"

monei_get_my_solana_address

Returns the user's Solana wallet address.

Inputs: none

Example prompt: "What's my Solana address? I want to receive SOL."

monei_get_supported_networks

Lists all supported EVM chains with chain IDs and names.

Inputs: none

Example prompt: "What chains do you support?"

Deposits

monei_generate_deposit_link

Generates a payment link the user can open to deposit NGN.

Inputs:

Returns:

{
  "paymentLink": "string",
  "reference": "string"
}

Example prompt: "I want to deposit ₦50,000 into my Monei account"

monei_check_deposit_status

Checks the status of a deposit by reference.

Inputs:

Example prompt: "Did my deposit go through?"

NGN Payouts

monei_send_naira_to_bank

Sends NGN to a Nigerian bank account.

Inputs:

Always call monei_verify_bank_account first and show the account name to the user before sending.

Example prompt: "Send ₦20,000 to my GTBank account 0123456789"

monei_send_naira_to_user

Sends NGN to another Monei user by email or phone.

Inputs:

Example prompt: "Send ₦5,000 to john@gmail.com"

Banking utilities

monei_get_banks

Returns the full list of supported Nigerian banks with their codes.

Inputs: none

Example prompt: "What banks do you support?" / "What's the bank code for GTBank?"

monei_verify_bank_account

Verifies a bank account number and returns the account holder name.

Inputs:

Returns:

{
  "accountName": "string",
  "accountNumber": "string",
  "bankCode": "string"
}

Always call this before any bank payout and show the account name to the user for confirmation.

Example prompt: "Verify account 0123456789 at GTBank"

Crypto sends

monei_send_crypto_evm

Sends native tokens or ERC-20s on any supported EVM chain.

Inputs:

Example prompts:

• "Send 0.01 ETH to 0x742d..."

• "Send 100 USDT on BSC to 0x..."

monei_send_crypto_solana

Sends SOL or SPL tokens on Solana.

Inputs:

Example prompts:

• "Send 2 SOL to 5AH3..."

• "Send 50 USDC on Solana to 5AH3..."

Token swaps

monei_swap_tokens_evm

Swaps tokens on EVM. Routes automatically based on whether tokens are native or ERC-20.

Inputs:

Example prompts:

• "Swap 0.1 ETH for USDC on Base"

• "Swap 100 USDC for USDT on Polygon"

monei_swap_tokens_solana

Swaps tokens on Solana. Routes automatically between SOL and SPL tokens.

Inputs:

Example prompts:

• "Swap 1 SOL for USDC"

• "Swap 100 USDC for SOL"

Offramp

monei_get_offramp_quote

Gets the live exchange rate for selling crypto to NGN.

Inputs:

Example prompt: "What's the rate for selling 100 USDT on Base today?"

monei_sell_crypto_for_naira

Sells crypto and settles the proceeds to a Nigerian bank account.

Inputs:

Returns:

{
  "reference": "string",
  "status": "string",
  "amounts": { "crypto": {}, "fiat": {}, "exchangeRate": 0, "totalFee": 0 },
  "onChain": { "depositAddress": "string" }
}

Call monei_get_offramp_quote first to show the rate. Call monei_verify_bank_account to get the accountName. Show both to the user for confirmation before calling this.

Example prompt: "Sell 100 USDT on Base to my GTBank account 0123456789"

monei_track_offramp

Checks the status of an offramp transaction.

Inputs:

Statuses: initiated → awaiting_deposit → deposit_received → processing → fiat_sent → completed

Example prompt: "What's the status of my USDT sale?"

Bill payments

monei_get_bill_providers

Lists available billers and packages for a bill category.

Inputs:

Example prompts:

• "What MTN data plans are available?"

• "What electricity providers do you support?"

monei_pay_bill

Pays a bill. Routes to the correct payment method based on category.

Common inputs: category (required), plus category-specific fields:

All categories also accept isSchedule, scheduleData, saveBeneficiary, beneficiaryName.

Always call monei_get_bill_providers first to get valid biller and itemCode values.

Example prompts:

• "Buy ₦1,000 MTN airtime for 08012345678"

• "Pay ₦5,000 to my IKEDC meter 12345678901"

• "Subscribe DSTV Compact for smartcard 1234567890"

• "Pay my DSTV every month on the 1st"

monei_get_bill_history

Returns recent bill payment history across all categories.

Inputs: none

Example prompt: "Show my recent bill payments"

Transactions

monei_get_transaction_history

Returns recent wallet transactions.

Inputs: none

Example prompt: "Show my recent transactions"

monei_get_transaction

Gets a single transaction by ID or reference.

Inputs:

Example prompt: "What happened with transaction ref_abc123?"

Common agent patterns

These natural language prompts work well out of the box:

Check balance and send naira

"Check my balance, then send ₦10,000 to my GTBank account 0123456789. The bank code is 058."

Agent flow: get_wallet → verify_bank_account → confirm with user → send_naira_to_bank

Full offramp flow

"I want to sell 200 USDT on Polygon to my Access Bank account 0987654321"

Agent flow: get_offramp_quote → get_banks → verify_bank_account → show rate + account name → confirm → sell_crypto_for_naira → track_offramp

Buy airtime

"Buy ₦500 Airtel airtime for 08098765432"

Agent flow: get_bill_providers (AIRTIME, Airtel) → get_wallet → pay_bill

Swap and check

"Swap 0.05 ETH for USDC on Base, then show me my updated portfolio"

Agent flow: get_evm_portfolio → confirm → swap_tokens_evm → get_evm_portfolio

Peer transfer

"Send ₦2,000 to jane@example.com from my Monei wallet"

Agent flow: get_wallet → confirm balance → send_naira_to_user

Troubleshooting

Tools not showing up in Claude Desktop

• Check that MONEI_API_KEY is set in claude_desktop_config.json

• Restart Claude Desktop fully after config changes

• Check stderr logs: tail -f ~/Library/Logs/Claude/mcp*.log (macOS)

Authentication failed — your API key is invalid or expired

• Verify your API key in the Monei dashboard

• Make sure MONEI_ENV matches the environment your key belongs to (sandbox vs live)

• In HTTP/SSE mode, check the Authorization: Bearer header is being sent

Rate limit exceeded — please wait a moment

• The server automatically retries up to 3 times with exponential backoff

• If you see this in a tool response, the retries were exhausted — wait 30 seconds and try again

Session not found or expired (SSE mode)

• The SSE session expired (1 hour TTL) or the server restarted

• Re-open the /sse connection your MCP client will reconnect automatically in most cases

Zod validation errors on tool inputs

• The agent passed a wrong type (e.g. "100" instead of 100 for an amount)

• All amount fields use z.coerce.number() so string numbers are accepted

• If you see this, check the exact field name in the error message and fix the agent prompt

Security

• API keys never appear in logs, error messages, or stack traces

• Transaction PINs are request-scoped. never stored, cached, or logged

• Zod validation runs before the SDK is touched. invalid input is rejected immediately

License

MIT