Flutterwave MCP Server for AI Assistant Transactions

Overview

This MCP (Model Context Protocol) server connects AI assistants to Flutterwave so they can inspect and act on payments, webhooks, transfers, and beneficiaries. It exposes a set of MCP tools that let a conversational agent confirm transaction status, resend failed webhook notifications, create and disable payment links, and automate retry or transfer workflows — all while returning rich UI components when the MCP client supports them.

Built to integrate with MCP-enabled clients (for example Claude Desktop or MCP Inspector), the server also ships MCP-UI resources so transactions and links appear as branded, interactive cards and timelines inside the assistant interface. This makes it easier for developers to build AI-driven payment workflows, customer support automations, and operational tooling that require safe, auditable interactions with Flutterwave.

Features

• Confirm transaction status and fetch transaction details
• Resend failed webhook notifications to merchant endpoints
• Create and disable payment (checkout) links
• Retry failed transactions with guidance for recoverable errors
• Retrieve transaction history and timelines
• Create and manage transfers and beneficiaries
• Generate Flutterwave-branded rich UI cards and timelines (via MCP-UI)
• Works with MCP clients that render UI resources (resource type: “resource” with HTML)

Installation / Configuration

Install the package globally via npm (recommended):

npm install -g mcp-flutterwave

Or install and build from source:

git clone https://github.com/bajoski34/mcp-flutterwave.git
cd mcp-flutterwave
npm install
npm run build

Set your Flutterwave secret key in the environment before running:

export FLW_SECRET_KEY="YOUR_FLUTTERWAVE_SECRET_KEY"

Run the server using the installed binary:

mcp-flutterwave --tools=create-checkout,disable-checkout,get-transactions,resend-failed-webhook

Or run the built node script directly (local build):

node /path/to/mcp-flutterwave/build/index.js --tools=create-checkout,get-transactions

Notes:

• The --tools flag controls which tools the MCP server advertises. Use comma-separated tool ids.
• Ensure the process has network access to Flutterwave endpoints and to any merchant webhook endpoints you will resend.

Integrating with an MCP Client (example: Claude Desktop)

Add the server to your client config (example JSON snippet for Claude Desktop):

{
  "mcpServers": {
    "flutterwave": {
      "command": "mcp-flutterwave",
      "args": [
        "--tools=create-checkout,disable-checkout,get-transactions,resend-failed-webhook"
      ],
      "env": {
        "FLW_SECRET_KEY": "YOUR_SECRET_KEY"
      }
    }
  }
}

If running the built script locally, set “command” to “node” and the path to the built index.js as shown in the repo README.

Available Tools / Resources

The server exposes multiple MCP tools. Tool IDs and brief descriptions:

Tools return plain text responses and, when the client supports MCP-UI resources, HTML-based UI resources (type: “resource”) that render branded components (transaction cards, timelines, links).

Use Cases (concrete examples)

• Customer support assistant: An agent asks the assistant for the status of a payment. The assistant calls get-transactions with the transaction ID, displays a UI card showing amount, status, and timestamp, and suggests next steps (refund, retry, or escalate).
• Webhook recovery: A merchant receives an alert for a failed webhook delivery. The assistant invokes resend-failed-webhook to replay the notification to the merchant endpoint and returns success/failure metadata.
• Automating payment links: Sales or billing workflows create a payment link with create-checkout and share the clickable UI card inside the chat. If a link must be disabled, the assistant uses disable-checkout.
• Retry failed payments: For recoverable errors (temporary network or card issues), retry-transaction analyzes the failure reason and either suggests a customer-facing retry step or triggers an automated retry when safe.
• Transfers and payroll: Back-office tools use get-beneficiaries / create-beneficiary and create-transfer to programmatically manage payout flows and show transfer confirmations as UI cards for audit.

MCP-UI and Client Compatibility

• The server uses @mcp-ui/server to produce interactive HTML resources compatible with MCP clients that support the “resource” response type.
• MCP Inspector and Claude Desktop are known-compatible clients; other MCP clients may support UI resources as well — check the client documentation.
• UI components use Flutterwave’s brand colors and responsive HTML so they render well in both desktop and mobile MCP clients.

Troubleshooting & Security

• Ensure FLW_SECRET_KEY is valid and has appropriate permissions for the intended operations.
• For webhook resends, make sure the merchant endpoint is reachable from the machine running the MCP server.
• Check server logs for API error responses (rate limits, invalid keys, or malformed requests).
• Treat the FLW_SECRET_KEY as sensitive—do not commit it to source control or expose it in logs.

Repository and source code: https://github.com/bajoski34/mcp-flutterwave

If you plan to extend or contribute, follow the repo’s CONTRIBUTING.md and run the MCP Inspector to preview UI components during development.