Summary: 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_shop chains 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.
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.
You can run the server directly from GitHub without cloning or installing dependencies.
Add this to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"malipo": {
"command": "npx",
"args": ["-y", "github:Tunzaa/tunzaa_mcp"]
}
}
}Go to Settings -> Features -> MCP.
Click + Add New MCP Server.
Name: Malipo | Type: command | Value: npx -y github:Tunzaa/tunzaa_mcp
Add this to your ~/.codeium/config.json:
{
"mcpServers": {
"malipo": {
"command": "npx",
"args": ["-y", "github:Tunzaa/tunzaa_mcp"]
}
}
}Related MCP server: MCP Midtrans Documentation Server
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_shop to 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 create_demo_shop tool is the cornerstone of this platform. It doesn't just return data; it provides a Live Grounding Trace.
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."
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.
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.
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).
If you'd like to contribute or modify the server:
git clone https://github.com/Tunzaa/tunzaa_mcp.git
cd tunzaa_mcp && pnpm install && pnpm run build
Use the local path in your config: "args": ["/ABSOLUTE/PATH/TO/tunzaa_mcp/dist/index.js"]
ISC
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.
| Name | Required | Description | Default |
|---|---|---|---|
| api_url | No | Optional URL to simulate the Malipo environment for grounding. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It never discloses whether the Token/Payment/Installments calls create real records, whether state is mutated or rolled back, what auth or credentials are needed, or what happens if api_url is omitted. The vague framing as a 'grounding tool' and 'live trace' leaves the side-effect profile entirely unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, and the operative content is front-loaded reasonably, but 'The ultimate grounding tool' is pure marketing filler that earns no place. The remaining text is efficient but the opening sentence could be dropped without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool orchestrates a multi-step chain of API calls with likely side effects, yet there is no output schema, no annotations, and no description of what is returned or what state changes. The name/description mismatch about whether a 'demo shop' is created is left unresolved, so an agent lacks what it needs to invoke this safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single optional parameter with 100% schema description coverage, so the schema already documents api_url. The description adds no meaning about the parameter or what omitting it does, which is the baseline-3 case when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete action ('Executes a full sequence of Malipo API calls (Token -> Payment -> Installments)'), which is more than a tautology. However, it never reconciles this with the tool name 'create_demo_shop' — an agent cannot tell whether a demo shop resource is actually created or whether this is purely a trace/simulation, and no sibling is named to disambiguate it from get_token/initiate_payment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one intended context — 'Use this to see a live trace of the API, allowing you to generate perfect integration code' — which implies the grounding/onboarding scenario. But there are no when-not conditions and no comparison against the sibling tools that perform the same underlying calls individually.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new installment plan. Use this to understand the complex object structure required for installment-based payments.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the item or plan (e.g., 'Samsung S24 Ultra - 12 Month Plan'). | |
| address | No | ||
| customer | Yes | ||
| end_date | Yes | The expected completion date for all payments (YYYY-MM-DD). | |
| start_date | Yes | The date of the first installment payment (YYYY-MM-DD). | |
| description | Yes | Brief description of the product or service being financed. | |
| total_amount | Yes | The total price of the item to be paid in installments. | |
| custom_interval | No | Number of days between installments if frequency is 'custom'. | |
| payment_frequency | Yes | How often the customer will make payments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'complex object structure,' hinting at input complexity, but fails to disclose critical traits: whether this is a write operation (implied by 'create'), permission requirements, side effects (e.g., database changes), error handling, or response format. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences that are front-loaded: the first states the purpose, and the second adds context. There's no wasted text, but the second sentence could be more actionable (e.g., specifying key parameters). It's efficient but not perfectly structured for maximum clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, nested objects, no output schema, and no annotations), the description is incomplete. It doesn't address the mutation nature, potential side effects, error scenarios, or what happens after creation (e.g., returns a plan ID). For a tool with high parameter count and no structured safety hints, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 78% (high), so the baseline is 3 even with no parameter info in the description. The description adds minimal value beyond the schema by noting 'complex object structure,' but doesn't explain parameter interactions (e.g., 'custom_interval' depends on 'payment_frequency') or provide examples. It compensates slightly but not enough to raise the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a new installment plan.' It specifies the action (create) and resource (installment plan), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'edit_installment_plan' or 'initiate_payment,' which would require explicit comparison for a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance: 'Use this to understand the complex object structure required for installment-based payments.' This suggests it's for creating plans with structured data, but it lacks explicit when-to-use rules, alternatives (e.g., vs. 'edit_installment_plan'), or exclusions. No misleading information is present, but guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel/Delete an existing installment plan. Use this to verify the cancellation response structure.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| plan_id | Yes | The numeric ID of the plan to cancel/delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool performs a cancellation/deletion (implying a destructive mutation) and mentions verifying the response structure, but lacks critical behavioral details: it doesn't specify if the deletion is reversible, what permissions or authentication are required, any rate limits, side effects (e.g., impact on related payments), or error handling. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the primary action ('Cancel/Delete an existing installment plan.') and following with a secondary purpose. There is no wasted text, but the second sentence about verifying response structure feels somewhat disconnected and could be integrated more smoothly. Overall, it's efficient but not perfectly structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive mutation with 2 parameters, 50% schema coverage, no output schema, and no annotations), the description is incomplete. It lacks details on behavioral traits, full parameter meanings, output expectations, and usage context. The mention of response structure verification is insufficient to cover these gaps, making it inadequate for safe and effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'plan_id' has a description). The description adds no parameter-specific information beyond what the schema provides—it doesn't explain the 'address' parameter or provide additional context for 'plan_id'. With low schema coverage, the description fails to compensate for undocumented parameters, resulting in minimal added value. The baseline is adjusted downward due to the coverage gap, but the description doesn't worsen it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Cancel/Delete') and identifies the resource ('an existing installment plan'). It distinguishes from siblings like 'edit_installment_plan' and 'get_installment_plan' by focusing on removal rather than modification or retrieval. However, it doesn't explicitly differentiate from all siblings (e.g., 'create_installment' is for creation, but this is implied).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: it states to use this tool for cancellation/deletion, but offers no context on when to use it versus alternatives (e.g., when not to delete, prerequisites like plan status). It mentions verifying the cancellation response structure, which hints at a testing use case, but this is vague and doesn't clarify operational scenarios. No explicit when/when-not or alternative tool references are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing installment plan. Use this to understand which fields are mutable via the Malipo API.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| plan_id | Yes | The numeric ID of the plan to modify. | |
| updates | Yes | A map of fields to update (e.g., {'description': 'New description'}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It says the tool updates an existing plan but does not disclose permissions, whether updates are partial or destructive, how unspecified fields behave, or what the response contains. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loads the action. However, the second sentence is confusing and arguably misleading: it frames the tool as a way to understand mutable fields rather than to perform an update. The structure is compact but not fully purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations, no output schema, a nested updates object, and one undocumented parameter. The description does not cover required permissions, mutation behavior, field mutability details, or return expectations, leaving the agent materially under-informed for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with plan_id and updates described in the schema but address undocumented. The description adds no parameter-level detail; it does not list mutable fields, explain the updates map format beyond the schema example, or clarify the address parameter. It fails to compensate for the uncovered parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Update an existing installment plan.' This clearly identifies the action and distinguishes it from sibling tools like get_installment_plan, create_installment, and delete_installment_plan. It lacks sibling-specific routing guidance, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use versus alternatives guidance. The sentence 'Use this to understand which fields are mutable via the Malipo API' is more of a vague rationale than a usage rule, and it does not mention prerequisites, alternatives, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific installment plan. Use this to see the precise fields returned for a plan (status, schedules, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| plan_id | Yes | The unique numeric ID of the installment plan. | |
| include_payments | No | Append ?include_payments=true to also receive completed payment history and progress totals. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state whether the call is a safe read, what happens when plan_id does not exist, what auth is needed, or how the response is shaped beyond a vague 'status, schedules, etc.'
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action, with no filler. The second sentence is slightly redundant and vague ('precise fields'), but nothing is wasted at length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with no output schema and no annotations, an agent needs the safety profile and the error/missing-record behavior, neither of which appears. The mention of returned fields partially fills the no-output-schema gap but does not name the address parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: plan_id and include_payments already have schema descriptions, including the query-string mechanics of include_payments. The description adds no parameter guidance at all and leaves the undocumented 'address' parameter entirely unaddressed, so it does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (get a single installment plan) and hints at the content returned (status, schedules). It does not explicitly differentiate from the closest sibling, list_installments, so an agent must infer that this is the single-record lookup versus the collection listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence implies when to use it (to inspect the precise fields of a plan), but there is no explicit when-not, no prerequisite, and no named alternative such as list_installments for browsing. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the status of a payment transaction. Helpful for understanding the various status states (COMPLETED, PENDING, FAILED) for your application logic.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | ||
| transactionID | Yes | The 'transactionID' previously returned by 'initiate_payment'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool checks status and lists possible states (COMPLETED, PENDING, FAILED), which gives some context about expected behavior. However, it lacks details on permissions, rate limits, error handling, or whether it's idempotent, which are important for a payment-related tool. The description does not contradict annotations, but it's insufficient for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences that efficiently convey the tool's purpose and utility. It is front-loaded with the main action ('Check the status...') and avoids unnecessary details. However, it could be slightly more structured by explicitly separating usage guidance from purpose, but overall it's well-sized with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and moderate schema coverage, the description provides basic purpose and status context but lacks completeness. It does not explain return values, error cases, or dependencies (e.g., requiring a valid 'transactionID' from 'initiate_payment'), which are crucial for effective tool use. The description is adequate as a starting point but has clear gaps for a payment status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'transactionID' has a description). The description does not add meaning beyond the schema, as it does not explain parameters like 'address' or provide additional context for 'transactionID'. Since schema coverage is moderate, the baseline is 3, but the description fails to compensate for the undocumented 'address' parameter, leaving gaps in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Check') and resource ('status of a payment transaction'), distinguishing it from siblings like 'initiate_payment' (which creates payments) and 'get_installment_plan' (which retrieves plan details). It explicitly mentions the tool helps understand status states, which adds clarity about its informational role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating it's 'helpful for understanding the various status states... for your application logic,' suggesting it should be used to monitor payment outcomes. However, it does not explicitly state when to use this tool versus alternatives (e.g., vs. 'handle_callback' for real-time updates) or provide exclusions, leaving some ambiguity in context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a Malipo API access token. Refreshes internal token automatically. Use this to verify your API credentials and see the internal token structure.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | Optional override for the Malipo API base URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses an automatic internal token refresh (a side effect an agent should know about), but omits whether authentication is required, whether the returned value is sensitive secret material, and whether calls are rate-limited or cached.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the core action front-loaded and zero redundancy. It could be tightened further, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should carry more of the return-value burden. It gestures at the token structure but never describes what is actually returned or whether the token is a live credential that must be handled carefully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is a single optional parameter and schema description coverage is 100%, so the schema already documents the base-URL override. The description adds nothing about this parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieve a Malipo API access token. This is clearly distinguishable from the payment/installment siblings, which all deal with transactions rather than credentials. No explicit sibling routing is given, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this to verify your API credentials and see the internal token structure" gives one implied use case, but there is no when-not guidance, no prerequisites (e.g. does it require existing credentials?), and no mention of alternatives. Usage is inferable but thin.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate or handle the callback payload sent by Malipo to your webhook. Essential for grounding your webhook integration code with real payload examples.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | The amount confirmed by the provider as a decimal string (e.g., '1500.00'). | |
| status | Yes | The final status of the payment (e.g., 'COMPLETED', 'FAILED', 'CANCELLED'). | |
| timestamp | No | The event datetime as a string, e.g. '2024-11-25 16:45:10'. | |
| x_signature | No | The X-Signature header value. HMAC-SHA256 of the JSON payload with alphabetically sorted keys (Python json.dumps(payload, sort_keys=True) format) using your API secret key. | |
| payment_date | No | The date and time the payment was completed, e.g. '2024-11-25 14:30:45'. | |
| reference_id | No | Your system's unique order reference. | |
| transaction_id | Yes | The unique Malipo transaction ID sent in the webhook. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden and does not meet it. It never states whether the tool has side effects, whether it validates x_signature, whether 'handle' processes real events or only simulates, or what it returns. The simulate/handle ambiguity leaves the mutation profile entirely undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose statement and free of padding. Slightly weakened by the unresolved 'simulate or handle' phrasing, which adds ambiguity rather than information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With seven parameters, no annotations, and no output schema, the description needs to explain return behavior and side effects, and it does neither. An agent has no basis to decide whether calling this mutates state, what it produces, or how simulation differs from real handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all seven fields, including the x_signature HMAC scheme and timestamp formats. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (the callback payload Malipo sends to your webhook) but pairs two different verbs, 'simulate' and 'handle,' without clarifying which behavior the tool actually performs. An agent cannot tell whether this generates a sample payload or processes a real one. It is distinct from the payment/installment siblings, but the core action remains ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Essential for grounding your webhook integration code with real payload examples' implies a usage context (integration development), but gives no explicit when-to-use versus alternatives, no prerequisites, and no when-not guidance. It is implied usage rather than actionable routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Transaction amount as a string to avoid precision issues (e.g., '5000'). | |
| address | No | Optional override for API base URL. | |
| reference | Yes | Unique order reference from your system. Used to match callbacks. | |
| customer_msisdn | Yes | Customer phone number in international format without '+' (e.g., 255700000000). Essential for Mobile Money push. | |
| sandbox_scenario | No | In sandbox mode, forces the outcome of the payment push. Maps to the X-Sandbox-Scenario header. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does not disclose that this is a state-changing, money-moving call, whether it requires auth, how the reference is used for callback matching/idempotency, or what the sandbox_scenario does to real vs. test funds. The 'inspect the response structure' framing actually understates the side effects rather than clarifying them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no padding, but the second sentence does not earn its place: it introduces ambiguity about the tool's nature instead of clarifying invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a financial mutation tool with no annotations and no output schema, the description omits auth requirements, environment/sandbox behavior, idempotency of the reference, and error semantics. An agent has too little to invoke this safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters including amount, reference, customer_msisdn, address, and sandbox_scenario are already documented in the schema. The description adds no parameter meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb and resource ('Initiate a payment request... via Malipo API') and even the payment rail (M-Pesa). It gives no differentiation from siblings like get_payment_status or handle_callback, and the second sentence ('inspect the response structure') blurs whether this is a live payment tool or a scaffolding/inspection helper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It offers one usage claim ('Call this to inspect the response structure...') but never says when to use it versus get_payment_status or handle_callback, nor states prerequisites such as obtaining a token via get_token or running against a sandbox address.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List existing installment plans. Use this to see how pagination and plan summaries are returned by the Malipo API.
| Name | Required | Description | Default |
|---|---|---|---|
| from | No | Starting index for pagination (sent as query parameter). | |
| limit | No | Number of plans to return per page (sent as query parameter). | |
| address | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the disclosure burden. It conveys that the operation is a read ('list existing') and that pagination and plan summaries are returned, which is genuine return-format context, but it says nothing about auth requirements, rate limits, or empty-result behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, purpose front-loaded with no filler. The second sentence is somewhat idiosyncratic but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should characterize the response, and it only vaguely gestures at 'pagination and plan summaries.' Combined with no annotations and one undocumented parameter, the definition is minimally adequate but leaves real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: 'from' and 'limit' are documented in the schema, but 'address' has no description anywhere. The prose adds no meaning to any parameter, so the one undocumented field remains opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List existing installment plans'), which clearly distinguishes it from the singular get_installment_plan and create/delete siblings. It does not explicitly name those siblings, but the list-vs-get distinction is inferable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence ('Use this to see how pagination and plan summaries are returned') is a meta-note about API exploration rather than a when-to-use-vs-alternatives rule. No conditions or exclusions relative to get_installment_plan or the other listing/retrieval siblings are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0create_demo_shop1 field changedInput schema / properties / api_url / descriptionPrevious value: -"Optional URL to simulate the Tunzaa environment for grounding."New value: +"Optional URL to simulate the Malipo environment for grounding."get_installment_plan1 field changedInput schema / properties / include_paymentsAdded value: +{
+ "description": "Append ?include_payments=true to also receive completed payment history and progress totals.",
+ "type": "boolean"
+}get_token1 field changedInput schema / properties / address / descriptionPrevious value: -"Optional override for the Tunzaa API base URL."New value: +"Optional override for the Malipo API base URL."handle_callback5 fields changedInput schema / properties / amount / descriptionPrevious value: -"The amount confirmed by the provider."New value: +"The amount confirmed by the provider as a decimal string (e.g., '1500.00')."Input schema / properties / payment_date / descriptionPrevious value: -"The date the payment was completed."New value: +"The date and time the payment was completed, e.g. '2024-11-25 14:30:45'."Input schema / properties / timestamp / descriptionPrevious value: -"UNIX timestamp of the event."New value: +"The event datetime as a string, e.g. '2024-11-25 16:45:10'."Input schema / properties / transaction_id / descriptionPrevious value: -"The unique Tunzaa transaction ID sent in the webhook."New value: +"The unique Malipo transaction ID sent in the webhook."Input schema / properties / x_signatureAdded value: +{
+ "description": "The X-Signature header value. HMAC-SHA256 of the JSON payload with alphabetically sorted keys (Python json.dumps(payload, sort_keys=True) format) using your API secret key.",
+ "type": "string"
+}initiate_payment2 fields changedInput schema / properties / customer_msisdn / descriptionPrevious value: -"Customer phone number in local format (e.g., 0744550667). Essential for Mobile Money push."New value: +"Customer phone number in international format without '+' (e.g., 255700000000). Essential for Mobile Money push."Input schema / properties / sandbox_scenarioAdded value: +{
+ "description": "In sandbox mode, forces the outcome of the payment push. Maps to the X-Sandbox-Scenario header.",
+ "enum": [
+ "success",
+ "failure"
+ ],
+ "type": "string"
+}list_installments4 fields changedInput schema / properties / from / defaultRemoved value: -0Input schema / properties / from / descriptionPrevious value: -"Starting index for pagination."New value: +"Starting index for pagination (sent as query parameter)."Input schema / properties / limit / defaultRemoved value: -20Input schema / properties / limit / descriptionPrevious value: -"Number of plans to return per page."New value: +"Number of plans to return per page (sent as query parameter)."v1.0.0create_demo_shopcreate_installmentdelete_installment_planedit_installment_planget_installment_planget_payment_statusget_tokenhandle_callbackinitiate_paymentlist_installmentsScored 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.
Stripe payments for AI agents. Create links, verify, manage customers.
Let AI agents add Yolfi crypto checkout, paylinks, webhooks, and status checks.
Approval layer for AI agent payments: rules, budgets, human approvals. Sandbox, test credentials.
Pakistan payments for AI agents — Safepay checkout via Safepay. Never holds funds.
