@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"
      }
    }
  }
}

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | MONEI_API_KEY | Yes (stdio) | — | Your Monei API key. Not required in HTTP/SSE mode — pass via Authorization: Bearer header instead | | MONEI_TRANSPORT | No | stdio | Transport mode: stdio, http, or sse | | PORT | No | 3000 | HTTP/SSE server port | | MONEI_TIMEOUT | No | 30000 | Request timeout in milliseconds. Max 120000 | | MONEI_API_URL | No | https://api.monei.cc | Override the live API base URL |

Transport modes

| Mode | Use case | How to start | |---|---|---| | stdio | Claude Desktop, local Cursor | Default — just run the server | | http | Custom agents, API integrations | MONEI_TRANSPORT=http node dist/index.js | | sse | Cursor remote, Claude.ai | MONEI_TRANSPORT=sse node dist/index.js |

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: | Field | Type | Required | Description | |---|---|---|---| | chainId | number | Yes | Chain ID. 56=BSC, 137=Polygon, 8453=Base, 1=Ethereum |

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: | Field | Type | Required | Description | |---|---|---|---| | amount | number | Yes | Amount in NGN to deposit |

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: | Field | Type | Required | Description | |---|---|---|---| | reference | string | Yes | Reference from monei_generate_deposit_link |

Example prompt: "Did my deposit go through?"

NGN Payouts

monei_send_naira_to_bank

Sends NGN to a Nigerian bank account.

Inputs: | Field | Type | Required | Description | |---|---|---|---| | amount | number | Yes | Amount in NGN | | bankCode | string | Yes | Bank code from monei_get_banks | | accountNumber | string | Yes | 10-digit account number | | transactionPin | string | Yes | User's 4-6 digit transaction PIN | | narration | string | No | Transfer description |

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: | Field | Type | Required | Description | |---|---|---|---| | receiver | string | Yes | Recipient email or phone number | | amount | number | Yes | Amount in NGN | | transactionPin | string | Yes | User's 4-6 digit transaction PIN |

Example prompt: "Send ₦5,000 to [email protected]"

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: | Field | Type | Required | Description | |---|---|---|---| | accountNumber | string | Yes | 10-digit bank account number | | bankCode | string | Yes | Bank code from monei_get_banks |

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: | Field | Type | Required | Description | |---|---|---|---| | to | string | Yes | Recipient wallet address (0x...) | | amount | string | Yes | Amount to send as a string (e.g. "0.1") | | chainId | number | Yes | Chain ID | | tokenAddress | string | No | ERC-20 contract address. Omit for native token sends |

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: | Field | Type | Required | Description | |---|---|---|---| | to | string | Yes | Recipient Solana address | | amount | string | Yes | Amount to send | | tokenMintAddress | string | No | SPL token mint address. Omit for SOL sends |

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: | Field | Type | Required | Description | |---|---|---|---| | amount | string | Yes | Amount to swap | | chainId | number | Yes | Chain ID | | tokenIn | string | No | ERC-20 contract to sell. Omit when selling native token | | tokenOut | string | No | ERC-20 contract to buy. Omit when buying native token | | slippageBps | number | No | Slippage tolerance in basis points. Default: 50 (0.5%) |

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: | Field | Type | Required | Description | |---|---|---|---| | amount | number|string | Yes | Amount to swap | | inputMint | string | No | Mint address of token to sell. Omit when selling SOL | | outputMint | string | No | Mint address of token to buy. Omit when buying SOL | | slippageBps | number | No | Slippage tolerance in basis points. Default: 50 (0.5%) |

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: | Field | Type | Required | Description | |---|---|---|---| | token | string | Yes | Token to sell: USDT, USDC, or CNGN | | network | string | Yes | Network: base, polygon, arbitrum-one, bnb-smart-chain, ethereum, optimism | | amount | number | Yes | Amount of token to sell | | fiat | string | No | Fiat to receive. Default: NGN |

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: | Field | Type | Required | Description | |---|---|---|---| | amount | number | Yes | Amount of token to sell | | token | string | Yes | Token to sell: USDT, USDC, or CNGN | | network | string | Yes | Network the token is on | | fiatCurrency | string | No | Default: NGN | | bankCode | string | Yes | Destination bank code | | accountNumber | string | Yes | Destination account number | | accountName | string | Yes | Account holder name from monei_verify_bank_account |

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: | Field | Type | Required | Description | |---|---|---|---| | reference | string | Yes | Reference from monei_sell_crypto_for_naira |

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: | Field | Type | Required | Description | |---|---|---|---| | category | string | Yes | AIRTIME, MOBILEDATA, CABLEBILLS, or UTILITYBILLS | | billerName | string | Conditional | Required for non-electricity categories (e.g. MTN, DSTV) |

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:

| Category | Required fields | |---|---| | AIRTIME | phoneNumber, biller, amount | | MOBILEDATA | phoneNumber, biller, itemCode | | UTILITYBILLS | meterNumber, disco, amount | | CABLEBILLS | smartcardNumber, biller, itemCode |

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: | Field | Type | Required | Description | |---|---|---|---| | reference | string | Yes | Transaction ID or reference string |

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 [email protected] 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