Send Airtime
airtime_sendDestructive
Send airtime top-up to any MTN, Safaricom, Airtel, or Vodafone subscriber. Common use cases include NGO field incentives, survey rewards, and agent payouts. Sandbox mode returns no real airtime for testing.
Instructions
Send airtime top-up to any MTN/Safaricom/Airtel/Vodafone subscriber. Common use: NGO field incentives, survey rewards, agent payouts. No real airtime sent in sandbox mode.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| phone | Yes | Recipient phone in E.164 format e.g. '+254712345678' | |
| amount | Yes | Amount as string e.g. '50' (KES 50). Minimum KES 10 in production. | |
| currency_code | No | ISO currency code: KES, NGN, GHS, UGX, TZS, RWF, ZAR | KES |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/mpesa_mcp/server.py:318-342 (handler)The airtime_send handler function that sends airtime top-up via Africa's Talking API. Takes phone, amount, and currency_code, calls the AT Airtime API, and returns success/status/amount/request_id/error.
def airtime_send( phone: Annotated[str, "Recipient phone in E.164 format e.g. '+254712345678'"], amount: Annotated[str, "Amount as string e.g. '50' (KES 50). Minimum KES 10 in production."], currency_code: Annotated[str, "ISO currency code: KES, NGN, GHS, UGX, TZS, RWF, ZAR"] = "KES", ) -> dict: """ Send airtime top-up to any MTN/Safaricom/Airtel/Vodafone subscriber. Common use: NGO field incentives, survey rewards, agent payouts. No real airtime sent in sandbox mode. """ at = _at_airtime() response = at.send(phone_number=phone, amount=amount, currency_code=currency_code) recipients = response.get("responses", []) if recipients: r = recipients[0] return { "success": r.get("status") == "Success", "status": r.get("status"), "amount": r.get("amount"), "request_id": r.get("requestId"), "error": r.get("errorMessage") if r.get("status") != "Success" else None, } return {"success": False, "error": "No response from API", "raw": response} - src/mpesa_mcp/server.py:311-317 (registration)The @mcp.tool annotation registering airtime_send as an MCP tool with title 'Send Airtime' and metadata annotations.
@mcp.tool(annotations={ 'title': 'Send Airtime', 'readOnlyHint': False, 'destructiveHint': True, 'idempotentHint': False, 'openWorldHint': True, }) - src/mpesa_mcp/server.py:92-97 (helper)Helper function _at_airtime() that initializes Africa's Talking SDK and returns the Airtime service instance.
def _at_airtime(): africastalking.initialize( username=os.environ["AT_USERNAME"], api_key=os.environ["AT_API_KEY"], ) return africastalking.Airtime - src/mpesa_mcp/server.py:318-322 (schema)Input schema for airtime_send: phone (E.164 string), amount (string), currency_code (string, defaults to 'KES'). Return type is dict.
def airtime_send( phone: Annotated[str, "Recipient phone in E.164 format e.g. '+254712345678'"], amount: Annotated[str, "Amount as string e.g. '50' (KES 50). Minimum KES 10 in production."], currency_code: Annotated[str, "ISO currency code: KES, NGN, GHS, UGX, TZS, RWF, ZAR"] = "KES", ) -> dict: