MCP tools

The MCP server, mpesa-daraja on PyPI, gives your agent mpesa_* tools that call Daraja. Add it to your agent with the steps in Agent setup.

Example

You ask in plain words. The agent picks the tools, and every money tool answers with the same result shape.

Check my M-Pesa credentials, then send a KES 1 STK push to 07XXXXXXXX and tell me when it's paid.

status is SUCCESS or FAILED once the outcome is known, ACCEPTED when Daraja has only taken the request, and UNKNOWN when the outcome must be checked before anything is retried.

Tools

Tool annotations mark money-moving tools as destructiveHint, so MCP clients ask for approval.

Safety

• Defaults to the sandbox.
• In production, money-moving tools refuse to run unless DARAJA_ALLOW_LIVE_MONEY_MOVEMENT=true.
• Optional guardrails, all off until set:
  • DARAJA_READ_ONLY=true hides every tool that moves money or writes. Use it for support bots, reconciliation and learning.
  • DARAJA_APPROVAL_THRESHOLD=5000: B2C, B2B, tax and reversals above KES 5,000 pause for a yes/no in the chat (MCP elicitation). Clients that can't show the prompt get a refusal, and nothing is sent. Collections (STK, B2B Express, Ratiba) never prompt, because the payer enters their own PIN.
  • DARAJA_ALLOWED_RECIPIENTS=07XXXXXXXX,600000: payouts may go only to these phones and shortcodes.
  • For a B2C refund, pass refund_of with the original M-Pesa receipt; it appears in the approval prompt and the remarks.
• Callback URLs must be HTTPS; C2B URLs with mpesa/safaricom in them are rejected up front.
• Tokens and secrets are never returned in tool output.
• Responses with ResponseCode "0" are tagged _note: ACCEPTED for processing only, so the agent does not report them as completed payments.
• Idempotent money tools. Each request is stored under an idempotency key. Repeating the key returns the stored request (duplicate: true) instead of paying again.
  • Only a definitively FAILED request is re-sent.
  • ACCEPTED or UNKNOWN requests (queue timeouts, network errors) are never re-sent until their result is known.
  • B2C, B2B and B2B Express require an explicit idempotency_key, e.g. refund-order-1042. Reversal, tax and Ratiba derive one from the transaction ID, the PRN and phone + name respectively. For STK the key is optional.

Configuration

Commands and configuration files

Install once with uv tool install mpesa-daraja-mcp to get the mpesa command (or prefix any command with uvx mpesa-daraja-mcp instead of mpesa):

mpesa init                 # guided: keys (hidden input), live check, save, register with your agents
mpesa status               # what's configured (masked), the guardrails, and a live key check
mpesa dev                  # callback receiver + tunnel (cloudflared or ngrok) + a live log of callbacks
mpesa serve [--http]       # the MCP server: stdio for local agents, HTTP for remote ones
mpesa up --domain pay.example.com   # self-host with Docker and automatic HTTPS
mpesa pay stk 07XXXXXXXX 10 --ref order-42     # waits for the PIN and shows the outcome
mpesa pay b2c 07XXXXXXXX 500 --key refund-42 --refund-of NLJ7RT61SV
mpesa result <id>   ·   mpesa balance   ·   mpesa explain 1032
mpesa skills install       # copy the Agent Skills into Claude Code, Codex, Cursor, …
mpesa upgrade

Every data command takes --json, and mpesa --verbose … logs each HTTP request to Daraja. A failed STK Push shows the --key to retry it with. Payments use the same guardrails as the MCP tools, and approvals are asked in the terminal. uvx mpesa-daraja-mcp with no arguments is the MCP server on stdio, which is what your agent runs.

The server needs no flags or environment variables in your agent's config. Settings are read in this order, highest first:

1. Environment variables, e.g. from the client's env block.
2. A project .env in the folder the agent starts the server in, or the file named by DARAJA_DOTENV. Only DARAJA_* lines are read.
3. The user config file that setup writes: ~/.config/mpesa-daraja-mcp/config.env (Windows: %APPDATA%\mpesa-daraja-mcp\config.env; override the folder with DARAJA_CONFIG_DIR). It is readable only by you.

The server starts even when unconfigured. Tools then explain what's missing, and mpesa_setup_status lists the gaps for each toolset without revealing any values.

To register by hand: claude mcp add --scope user mpesa -- uvx mpesa-daraja-mcp. Every other agent is covered in docs/clients.md. Once installed, the mpesa-daraja and mpesa-mcp command names also work as aliases for mpesa.

Remote access (HTTP mode)

mpesa serve --http serves MCP at /mcp and Daraja callbacks at /cb/<token>/… on one port, for n8n, cloud agents and teammates. It needs DARAJA_MCP_TOKEN, and starts read-only with every payout needing approval unless you say otherwise. Docker, HTTPS and n8n guides: https://github.com/Mr-Macharia/mpesa-daraja-skills-and-mcp/blob/main/docs/self-hosting.md

Results and callbacks

Every money or async tool returns one shape:

{"status": "ACCEPTED | SUCCESS | FAILED | UNKNOWN", "message": "...", "idempotency_key": "...",
 "duplicate": false, "ids": {"checkout_request_id": "..."}, "receipt": "...", "result_code": "...",
 "explanation": "...", "raw": {}}

To let the agent see final results, enable the built-in receiver:

export DARAJA_CALLBACK_LISTEN=127.0.0.1:8787
export DARAJA_CALLBACK_TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(24))")
ngrok http 8787                        # sandbox; use a reverse proxy with TLS in production
export DARAJA_CALLBACK_BASE_URL=https://<tunnel-host>

Callbacks are stored in DARAJA_STATE_DB:

• mpesa_get_result(id) reads them.
• mpesa_stk_push_and_wait returns the final outcome in one call.
• Queue-timeout callbacks are recorded as UNKNOWN.
• C2B validation requests are always accepted. Use your own receiver if you need to reject payments.

Without the receiver, mpesa_stk_push_and_wait still works through STK Query. For other APIs, paste a received payload into mpesa_parse_callback.

Load only the tools you need

Every tool the server offers takes up space in your agent's context, even when it's never called. Set DARAJA_TOOLSETS to the groups you use, and the agent sees only those tools. The basic tools (core) are always on; leave the setting unset to load everything.

The groups are stk, c2b, payouts, ops, qr, ratiba and billmanager.