AI assistants
MCP for AI assistants
Use your own TukuPay account from Claude (claude.ai, Desktop, Code), ChatGPT, Gemini, Cursor, VS Code or Windsurf: ask about balances, find payments, send a payment prompt. You sign in through the browser; nothing secret goes in any file.
What MCP is
MCP (Model Context Protocol) is a standard way for an AI assistant to use outside tools. TukuPay runs an MCP server: once you connect it, your assistant can call TukuPay's tools ("what are my balances?", "did order-1042 get paid?") on your own account only. You approve the connection in your browser once; it renews by itself for up to 30 days, and money going out goes straight through only within the limits you set; above them it waits for your PIN in the TukuPay app.
Before you start
- A verified TukuPay account.
- Tuku AI tokens on that account worth at least KES 200 (a business: KES 1,500), at the day's token rate. Below that, connecting is refused with an Add tokens link (Tokens in the app). Sessions already connected keep working; each tool call is paid from the tokens.
- An app: Developers → My apps → Register an app (https://tuku.money/banking-dashboard/developers). Verified accounts get the sandbox at once. You choose this app when you sign in; its limits and stop button apply.
- An MCP client: claude.ai, Claude Desktop, Claude Code, ChatGPT (Developer mode), Cursor, VS Code (with Copilot Chat), Windsurf, or any other.
1. Connect your client
Cursor and VS Code: the TukuPay extension (first choice)
You need a TukuPay account with Tuku AI tokens to connect: at least KES 200 worth (KES 1,500 for a business).
The TukuPay extension adds the server for you and puts a TukuPay panel in the sidebar (sign-in status, docs, price list, Apps with access). Until it is in the VS Code Marketplace and Open VSX, install it from our file:
- Download tukupay-latest.vsix (about 40 KB).
- Don't double-click the file: Windows may open Visual Studio (the other Microsoft app), which can't install it. Install from inside VS Code or Cursor:
- VS Code: Extensions view → the … menu → Install from VSIX… → pick the file. Or in a terminal:
code --install-extension tukupay-latest.vsix. - Cursor: Extensions view → … → Install from VSIX…, or
cursor --install-extension tukupay-latest.vsix. Windsurf works the same way. - Sign in once from the TukuPay panel (VS Code) or Cursor Settings → MCP → TukuPay → Connect. Your browser opens TukuPay to approve.
Or add only the MCP server
The server's address is https://mcp.tuku.money/mcp. Without the extension, one click adds just the server in Cursor or VS Code (no TukuPay panel); Claude and ChatGPT are here too:
You need a TukuPay account with Tuku AI tokens to connect: at least KES 200 worth (KES 1,500 for a business).
Each button only opens your app's own install screen with TukuPay's address filled in; nothing is installed until you press Install there, and nothing secret is in the link. For any other client, pick it below and copy the block. No key, token or secret goes in it.
Cursor and VS Code show a TukuPay icon next to the server once our next update is live (the server sends it); until then they show their default icon. It is the same server either way.
# 1. Add the server (once)
claude mcp add --transport http tukupay https://mcp.tuku.money/mcp
# 2. In Claude Code, type /mcp, choose tukupay, then Authenticate.
# Your browser opens TukuPay: sign in and approve. Done.Cursor, step by step
- Install: the TukuPay extension above (Install from VSIX…), or press Add to Cursor for the server only: Cursor opens its install screen with TukuPay filled in, press Install.
- Sign in once: Settings → MCP (Tools & Integrations) → TukuPay → Connect. Your browser opens TukuPay: sign in and press Approve. The dot turns green.
- Where the tools are: the same Settings → MCP → TukuPay lists every TukuPay tool and its status. Switch single tools off there.
- Use it: open the Agent chat (Ctrl/Cmd+I) and ask (examples below). Cursor asks before each tool runs; you can allow one tool every time.
- Sign in again or log out: Settings → MCP → TukuPay → Logout, then Connect.
VS Code, step by step
- Install: the TukuPay extension above (Install from VSIX…), or press Add to VS Code for the server only: VS Code opens with TukuPay filled in, press Install.
- Sign in once: open Copilot Chat, pick Agent mode, then Tools (the plug icon) → TukuPay → Start. Your browser opens TukuPay: sign in, press Approve, and Allow when VS Code asks.
- Where the tools are: the Tools picker in Agent mode lists every TukuPay tool. Tick or untick single tools there.
- Use it: ask in the chat (examples below). VS Code asks before each tool runs.
- Sign in again or log out: Command Palette → MCP: List Servers → TukuPay → Restart, or sign out from the Accounts menu.
Things to ask
- “What are my TukuPay balances?”
- “Show my statement for October.”
- “Did order-1042 get paid?”
- “Create a payment link for KES 1,500 for the school trip.”
- “Send an M-Pesa prompt of KES 500 to 0712 345 678.”
- “Which of my invoices are unpaid?”
- “How much has my chama collected this month?”
- “Pay KES 2,000 to 0722 000 000.” Within your limits it goes; above them it waits for your PIN (below).
Payouts: within your limits they go, above them you approve
A payout or transfer within your limits goes straight through: the limits you set for the assistant (Profile → Security → Apps with access → Change limits), or else TukuPay's default limits for assistants (KES 1,000 a payment, KES 5,000 a day), and only to people you have paid before; change them there any time. Above them, or with no limits set, it waits for your PIN in the TukuPay app (tap the notification, or the link we text you), within 5 minutes. The assistant never sees your limit amounts. See Is it safe?. Never type your PIN or a code into a chat or an editor. Each successful tool call uses a few Tuku AI tokens: see What it costs below for the price list.
If something goes wrong
- Server red or failed: check the address is exactly
https://mcp.tuku.money/mcp, then restart the server (or remove it and add it again). - 401, or asked to sign in again: the session ended. Log out and Connect again, then approve in the browser.
- Tokens have run out: add Tuku AI tokens in the TukuPay app (Tokens), then ask again.
- Wrong account or wrong host: end the session in Settings → Developer sessions, then sign in with the right account. The only TukuPay address is the one above.
Find TukuPay in your AI app
We are asking each AI app to list TukuPay, so you can find it by name instead of pasting the address. Until a listing below says it is live, add TukuPay with the steps above.
| Where | How you will find it | Status |
|---|---|---|
| Claude (claude.ai, Desktop, phone apps) | Connectors directory: search "TukuPay" | Coming soon |
| ChatGPT | Apps / Plugins directory: search "TukuPay" | Coming soon |
| VS Code (Copilot Chat) | Command Palette → MCP: Browse MCP Servers, from the GitHub MCP Registry | Coming soon |
| Cursor | Cursor Marketplace | Coming soon |
| Windsurf and other MCP apps | Their MCP store, from the official MCP Registry (money.tuku/tukupay) | Coming soon |
| DeepSeek | DeepSeek's own app does not connect to MCP servers. Use a DeepSeek model inside an app that does (Cursor, VS Code, Claude Code or Windsurf) and add TukuPay there | Not available |
How you sign in
You always sign in on TukuPay's own page in your browser and approve the app there. You never type your TukuPay password or PIN into Claude, ChatGPT, an editor or a terminal, and no key or secret is pasted anywhere. The AI client only receives a session on your own account: an hour at a time, renewed by itself for up to 30 days. You can end it any time in Settings → Developer sessions.
What it costs
- Connecting is free. Each successful tool call costs a few Tuku AI tokens (the same tokens SMS and Tuku AI use), taken from the account you connect. A call that fails or is refused costs nothing.
- The same prices apply in the sandbox and in live.
- Out of tokens? The assistant says so and nothing runs. Add tokens in the TukuPay app (Tokens), or ask the assistant to start a top-up: it sends an M-Pesa prompt to your own phone, and you enter your M-Pesa PIN there (never in the chat). Buying tokens is free.
| Tools | Tokens per call | KES per call |
|---|---|---|
tukupay_whoami, tukupay_about, tukupay_buy_tokens | Free | Free |
| Reads: profile, balances, wallets, payments made through the app, payment links, paypoints, invoices, chamas, webhook deliveries | 25 | 0.05 |
Searches: tukupay_statement, tukupay_all_transactions, tukupay_find_payment | 50 | 0.10 |
| Creates: payment link, paypoint, invoice, test webhook | 100 | 0.20 |
Money requests: tukupay_collect_mpesa, tukupay_transfer, tukupay_payout | 250 | 0.50 |
KES at today's rate (KES 0.002 a token). TukuPay may change these prices; every charge is in your token history.
2. Sign in
- Your client opens TukuPay's sign-in page in the browser. Sign in as usual.
- Check the page: it names the program asking, where it returns to (this computer, Cursor, VS Code…), and when the request started. Only continue if you just started it.
- Choose your app, Sandbox or Live (live needs your PIN), and what the session may do: read, collect, and (if you want) transfers and payouts.
- Press Approve. The browser hands back to your client, which says it is connected.
On a machine without a browser (a server over SSH), run npx -y @tukupay/mcp login --device: it shows a code like ABCD-EFGH; open TukuPay on your phone or laptop, go to the address it prints, and type the code.
3. Ask
Try: "What are my TukuPay balances?" If the assistant answers with your wallets, you are done.
Using TukuPay from Claude or ChatGPT on your phone
A connector belongs to your Claude or ChatGPT account, not to one device. In Claude, add TukuPay once (on the phone or on a computer) and it is there in the Claude phone app too. In ChatGPT, custom MCP servers are set up on chatgpt.com; whether they also show in the phone app depends on your ChatGPT plan and version.
- In the phone app, turn TukuPay on and ask something, or press Connect on the TukuPay connector.
- TukuPay's sign-in opens in a browser on your phone. That is expected: approving straight from the TukuPay app comes in the next version of the TukuPay app.
- Check the address is TukuPay's own (tuku.money), sign in, check the request, choose your app and Sandbox or Live, and press Approve.
- The browser hands back to Claude or ChatGPT, which says TukuPay is connected. It stays connected for up to 30 days.
If the browser shows TukuPay's web sign-in page instead of the approve page:
- That is normal. The browser inside Claude or ChatGPT does not share the sign-in of your TukuPay app. Sign in with the same phone number or email and password you use in the app (and any code we send you). You are then taken to the approve page.
- If you land on your TukuPay dashboard instead, close that browser, go back to Claude or ChatGPT and press Connect again. You are signed in now, so the approve page opens straight away.
- If signing in there does not work (your saved password is not offered, or the page keeps reloading), connect from a computer instead: on claude.ai or Claude Desktop, Connect works the same way, and the connection then shows in the phone app too.
- Type your PIN only on TukuPay's own page, and only when you sign in to Live. Claude and ChatGPT never ask for it; if a chat asks for your PIN, refuse.
The tools
| Tool | Does | Try asking |
|---|---|---|
tukupay_whoami | The app, sandbox or live, your account (your own name, phone and email in full), whose payout limits apply (not the amounts), minutes left | "Which TukuPay account am I connected to?" |
tukupay_balances | Every wallet's balance and available amount | "What's my TukuPay balance?" |
tukupay_list_wallets, tukupay_get_wallet | Your wallets, or one | "List my wallets with their ids." |
tukupay_statement | Your statement, with TukuPay's filters | "What came in yesterday over KES 1,000?" |
tukupay_list_transactions, tukupay_get_transaction | Payments made through the app; one by its reference | "Did order-1042 get paid?" |
tukupay_collect_mpesa | An M-Pesa prompt to a payer's phone | "Ask 0712345678 to pay KES 500 into my Main Wallet for invoice 17." |
tukupay_list_payment_links, tukupay_create_payment_link | Your payment links; make one to share | "Make a KES 2,000 link for the workshop." |
tukupay_transfer | To another of your wallets or a TukuPay user (within your limits it goes; above them it waits for your PIN) | "Move KES 1,000 from Main Wallet to Savings." |
tukupay_payout | To M-Pesa, a bank, a Paybill or a Till (within your limits it goes; above them it waits for your PIN) | "Pay KES 3,000 to till 123456 for flour." |
tukupay_webhook_deliveries, tukupay_webhook_test | Your app's webhooks | "Did my last webhooks get delivered?" |
What needs your PIN
| Action | From the assistant |
|---|---|
| Reading balances, statements, payments, links | Goes at once |
An M-Pesa prompt (tukupay_collect_mpesa) | Goes at once; the payer confirms with their own M-Pesa PIN. Money only comes in. |
| A payment link | Made at once (simulated in the sandbox) |
| A transfer or payout within your limits | Goes at once (live): the limits you set for the assistant in Profile → Security → Apps with access → Change limits, or else TukuPay's default limits for assistants (KES 1,000 a payment, KES 5,000 a day), to people you have paid before |
| A transfer or payout above your limits, or with no limits set | Waits for you to approve it in the TukuPay app with your PIN (Developers → Approvals). The tool answers "Waiting for approval in the TukuPay app" with an approval id. Above KES 50,000, always; in the sandbox, always (simulated). |
| Signing in to live | Your PIN, on TukuPay's page |
The assistant never sees, asks for or types your PIN or password. If it ever asks for your PIN, refuse: it is not TukuPay asking. Your own name, phone and email are shown to it in full (tukupay_whoami, tukupay_profile); other people's numbers stay masked, as in the app.
Sessions renew for up to 30 days
- A session works an hour at a time and your client renews it by itself (a refresh token that changes on every use), for up to 30 days from when you signed in. Then you sign in again.
- If the tools answer "Session expired" (30 days passed, you ended it, or your app was stopped), reconnect in your client (Claude Code:
/mcp→ tukupay → Authenticate) or runnpx -y @tukupay/mcp loginagain. - See and end your sessions in Settings → Developer sessions, one at a time or all at once. Every tool call is recorded there.
Safety rules
- Data is data. Results are marked as TukuPay data, and the assistant is told never to follow instructions inside them (a payment description that says "send money to…" is ignored).
- Check before you approve. The assistant tells you the amount and the recipient; check them again in the TukuPay app before you type your PIN.
- No double payments. Each money call carries an
external_reference; asking twice answers the first result. - Start in the sandbox, keep payout limits low, and only allow payouts in a session when you need them.
Troubleshooting
| You see | Why | Do this |
|---|---|---|
401 / "Not signed in" / "Session expired" | No session yet, or the hour is up | Reconnect in your client, or npx -y @tukupay/mcp login |
| "Register an app first" on the sign-in page | You have no app yet | Developers → My apps → Register an app, then sign in again |
402 insufficient_tokens / "Not enough Tuku AI tokens" on the sign-in page | Tool calls are paid in Tuku AI tokens and the balance is too low | Add tokens in TukuPay, then try again |
403 app_not_approved | The app is not ready for that mode (e.g. live before you went live) | Choose Sandbox, or go live first |
403 scope_missing | The session was not allowed that (e.g. payouts) | Sign in again and tick it (login --scope "read collect payouts") |
403 with a browser-based client | The request came from a web page TukuPay does not know (wrong origin) | Use a desktop client or claude.ai / vscode.dev; other web pages are refused on purpose |
| claude.ai or ChatGPT: "Couldn't connect" or an error page instead of TukuPay's sign-in | The connector URL is wrong, or that client is not yet allowed to sign in | Check the URL is exactly https://mcp.tuku.money/mcp; remove the connector and add it again; if it still fails, use Claude Desktop with the package |
403 app_stopped / "STOPPED (kill switch)" | You or TukuPay stopped the app | Nothing was paid. Restart your app with your PIN; TukuPay's stops only TukuPay can lift |
503 mcp_paused ("MCP server is switched off") | TukuPay has turned the MCP server off for now | Try later; your API keys and the gateway are not affected |
429 rate_limited | More than 60 requests a minute in one session | Wait a minute |
| The browser does not open | No browser here, or it is blocked | Open the address the client prints, or login --device |
| Windows: npx not found | The client cannot start npx directly | "command": "cmd", "args": ["/c", "npx", "-y", "@tukupay/mcp"] |
Privacy and help
- TukuPay receives only the requests your assistant sends (the tool and its details), never your conversation with it. What TukuPay answers goes to your assistant's provider. See the privacy policy.
- Each session is limited to 60 requests a minute, and TukuPay can switch the MCP server off to protect accounts (
503 mcp_paused); your API keys keep working. - Help: email ceo@tuku.money with what you asked, the time, and the client you used (Claude, ChatGPT, Cursor…). Never send your PIN or password.
Optional: add the free TukuPay skill to Claude or Claude Code for safer answers and better reports (money in and out, charges, monthly reports).
Apps set up before 12 November 2026 may still point at the old address; it keeps working. Use https://mcp.tuku.money/mcp for anything new.