Tunzaa MCP Server
OfficialSummary: The Malipo MCP Server gives AI agents grounding data, live/mock Tunzaa API tools, and golden code patterns to build accurate payment and installment integrations.
Authenticate — retrieve/refresh a Tunzaa access token (
get_token) to verify credentials and inspect token structure.Take payments — initiate mobile money requests (
initiate_payment) and check transaction states like COMPLETED, PENDING, or FAILED (get_payment_status).Handle webhooks — simulate or process Tunzaa callback payloads (
handle_callback) to ground webhook code with real examples.Manage installments — create, list, view, edit, and delete/cancel installment plans (
create_installment,list_installments,get_installment_plan,edit_installment_plan,delete_installment_plan).Run a live grounding trace —
create_demo_shopchains Token → Payment → Installment calls so agents can see the full API flow (sandbox/mock only).Read integrated docs — access MCP resources covering Auth, Payments, and Webhooks, plus embedded "golden" snippets for Express.js and React Hooks.
Operate in mock or live mode — golden mock data by default, or real sandbox/production verification via API credentials and optional host/base-URL overrides.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Tunzaa MCP Server generate a webhook handler for payment confirmations"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Malipo MCP Server
Grounding for AI-Driven Payment Integrations
The Malipo MCP Server is a developer-centric tool built for the community. It provides high-fidelity grounding data, integrated documentation, and "Golden" code patterns that allow AI agents (vibe coders) to generate perfect, non-hallucinated integration code for the Malipo by Tunzaa ecosystem.
🚀 Instant Start (Fastest Way)
You can run the server directly from GitHub without cloning or installing dependencies.
1. Claude Desktop
Add this to your claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"malipo": {
"command": "npx",
"args": ["-y", "github:Tunzaa/tunzaa_mcp"]
}
}
}2. Cursor
Go to Settings -> Features -> MCP.
Click + Add New MCP Server.
Name:
Malipo| Type:command| Value:npx -y github:Tunzaa/tunzaa_mcp
3. Windsurf
Add this to your ~/.codeium/config.json:
{
"mcpServers": {
"malipo": {
"command": "npx",
"args": ["-y", "github:Tunzaa/tunzaa_mcp"]
}
}
}Related MCP server: Yolfi MCP Server
🧭 The Vibe Coding Workflow
This server is designed to help you build Malipo integrations in minutes. Follow this flow with your AI assistant:
Grounding: Add this MCP server to your project.
Exploration: Ask the AI: "List the Malipo resources and read the authentication guide."
Simulation: Run the tool:
create_demo_shopto see a live trace of a successful integration.Generation: Ask the AI: "Based on the grounding trace and the node-express example, build a checkout page for my app."
🏪 The Grounding "Demo Shop"
The create_demo_shop tool is the cornerstone of this platform. It doesn't just return data; it provides a Live Grounding Trace.
How to use it:
Trigger the Simulation: Tell your AI agent: "Run the Malipo create_demo_shop tool to understand the payment flow."
Review the Trace: The agent will receive a chronological sequence of calls including Authentication, Payment Initiation, and Installment creation.
Production Implementation: Each step in the trace contains "Grounding Insights" that teach the agent how to handle state, headers, and reference IDs in your actual code.
Boilerplate: Ask the agent to "Convert the grounding trace into a [Node/Python/PHP] implementation using the best practices found in the documentation resources."
✨ Features
Integrated Documentation: AI agents can "read" guides on Auth, Payments, and Webhooks directly through MCP Resources.
Golden Patterns: Embedded code snippets for Express.js, React Hooks, and more.
Vibe Coder Optimized: Rich schema descriptions and instructional traces (via
create_demo_shop) ensure zero hallucination.Mock Mode by Default: Generates "Golden" mock data matching the real Malipo API structure.
Live Mode (Optional): Real-time verification against the Malipo Sandbox/Production.
🛠️ Usage (Live Mode)
To have the AI verify real data from your Malipo account (e.g., checking transaction statuses), add your credentials to the env block in your config:
"env": {
"MALIPO_API_KEY": "your_api_key",
"MALIPO_SECRET_KEY": "your_secret_key",
"MALIPO_ENVIRONMENT": "sandbox"
}Legacy
TUNZAA_*environment variables are still accepted as a fallback.
Optional settings
Variable | Default | Purpose |
|
| API host. Sandbox and production share this host and are selected by |
| (empty) | Comma-separated extra hosts that the tools' |
|
|
|
create_demo_shop initiates a real payment and creates a real installment plan, so it only runs when MALIPO_ENVIRONMENT=sandbox (or in mock mode).
🏗️ Local Development
If you'd like to contribute or modify the server:
git clone https://github.com/Tunzaa/tunzaa_mcp.gitcd tunzaa_mcp && pnpm install && pnpm run buildUse the local path in your config:
"args": ["/ABSOLUTE/PATH/TO/tunzaa_mcp/dist/index.js"]
License
ISC
Available Tools
10 toolscreate_demo_shopC
The ultimate grounding tool. Executes a full sequence of Malipo API calls (Token -> Payment -> Installments). Use this to see a 'live trace' of the API, allowing you to generate perfect integration code.
Inputs: api_url.
create_installmentB
Create a new installment plan. Use this to understand the complex object structure required for installment-based payments.
Inputs: name (required), customer (required), end_date (required), start_date (required), +5 more.
delete_installment_planC
Cancel/Delete an existing installment plan. Use this to verify the cancellation response structure.
Inputs: plan_id (required), address.
edit_installment_planC
Update an existing installment plan. Use this to understand which fields are mutable via the Malipo API.
Inputs: plan_id (required), updates (required), address.
get_installment_planB
Get details of a specific installment plan. Use this to see the precise fields returned for a plan (status, schedules, etc.).
Inputs: plan_id (required), address, include_payments.
get_payment_statusB
Check the status of a payment transaction. Helpful for understanding the various status states (COMPLETED, PENDING, FAILED) for your application logic.
Inputs: transactionID (required), address.
get_tokenB
Retrieve a Malipo API access token. Refreshes internal token automatically. Use this to verify your API credentials and see the internal token structure.
Inputs: address.
handle_callbackC
Simulate or handle the callback payload sent by Malipo to your webhook. Essential for grounding your webhook integration code with real payload examples.
Inputs: status (required), transaction_id (required), amount, timestamp, +3 more.
initiate_paymentC
Initiate a payment request (M-Pesa, etc.) via Malipo API. Call this to inspect the response structure needed to implement mobile money flows in your local code.
Inputs: amount (required), reference (required), customer_msisdn (required), address, +1 more.
list_installmentsB
List existing installment plans. Use this to see how pagination and plan summaries are returned by the Malipo API.
Inputs: from, limit, address.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target distinct actions and resources: auth, payment initiation, callback handling, installment CRUD, and payment status. create_demo_shop is a composite trace tool that overlaps with get_token, initiate_payment, and create_installment, and its name does not perfectly match its grounding purpose, but it remains distinguishable.
All names use consistent snake_case verb_noun patterns, such as get_token, initiate_payment, list_installments, and create_installment. Verbs like get, list, create, edit, and delete are used predictably across the set.
The set has 10 tools, which fits the payment and installment API domain well. Each tool appears to earn its place by covering a distinct operation or grounding scenario.
Installment plan coverage includes full CRUD plus listing, and payment coverage includes initiation, status, callback handling, and token retrieval. Minor gaps exist on the payment side, such as listing payments, retrieving full payment details, or refund/cancel operations, but agents can largely work around these.
Maintenance
Related MCP Connectors
Stripe payments for AI agents. Create links, verify, manage customers.
Let AI agents add Yolfi crypto checkout, paylinks, webhooks, and status checks.
Pakistan payments for AI agents — Safepay checkout via Safepay. Never holds funds.
Tanzania payments for AI agents — M-Pesa / Tigo Pesa via Flutterwave. Never holds funds.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables AI coding agents to safely integrate cross-border payments by providing structured payment knowledge, deterministic validation of idempotency, security, and state-machine rules, webhook testing, executable pytest generation, and diagnosis for Python/FastAPI Checkout projects.-
- FlicenseNot gradedqualityBmaintenanceEnables AI coding agents to add stablecoin checkout, payment links, payment status checks, and webhook verification to applications, plus webhook-based access logic after confirmed payments.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to integrate stablecoin checkout, payment links, payment status checks, webhook verification, and webhook-based entitlement logic into applications.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to set up crypto checkout integration by registering workspaces, creating paylinks and public payment invoices, configuring webhook endpoints, verifying webhook signatures, and checking stablecoin payment status.-