TukuPay Docs

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

  1. A verified TukuPay account.
  2. 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.
  3. 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.
  4. 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)

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:

  1. Download tukupay-latest.vsix (about 40 KB).
  2. 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:
  3. VS Code: Extensions view → the … menu → Install from VSIX… → pick the file. Or in a terminal: code --install-extension tukupay-latest.vsix.
  4. Cursor: Extensions view → … → Install from VSIX…, or cursor --install-extension tukupay-latest.vsix. Windsurf works the same way.
  5. 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:

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

  1. 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.
  2. Sign in once: Settings → MCP (Tools & Integrations) → TukuPay → Connect. Your browser opens TukuPay: sign in and press Approve. The dot turns green.
  3. Where the tools are: the same Settings → MCP → TukuPay lists every TukuPay tool and its status. Switch single tools off there.
  4. 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.
  5. Sign in again or log out: Settings → MCP → TukuPay → Logout, then Connect.

VS Code, step by step

  1. 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.
  2. 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.
  3. Where the tools are: the Tools picker in Agent mode lists every TukuPay tool. Tick or untick single tools there.
  4. Use it: ask in the chat (examples below). VS Code asks before each tool runs.
  5. 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.

WhereHow you will find itStatus
Claude (claude.ai, Desktop, phone apps)Connectors directory: search "TukuPay"Coming soon
ChatGPTApps / Plugins directory: search "TukuPay"Coming soon
VS Code (Copilot Chat)Command Palette → MCP: Browse MCP Servers, from the GitHub MCP RegistryComing soon
CursorCursor MarketplaceComing soon
Windsurf and other MCP appsTheir MCP store, from the official MCP Registry (money.tuku/tukupay)Coming soon
DeepSeekDeepSeek'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 thereNot 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.
ToolsTokens per callKES per call
tukupay_whoami, tukupay_about, tukupay_buy_tokensFreeFree
Reads: profile, balances, wallets, payments made through the app, payment links, paypoints, invoices, chamas, webhook deliveries250.05
Searches: tukupay_statement, tukupay_all_transactions, tukupay_find_payment500.10
Creates: payment link, paypoint, invoice, test webhook1000.20
Money requests: tukupay_collect_mpesa, tukupay_transfer, tukupay_payout2500.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

  1. Your client opens TukuPay's sign-in page in the browser. Sign in as usual.
  2. 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.
  3. 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.
  4. 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.

  1. In the phone app, turn TukuPay on and ask something, or press Connect on the TukuPay connector.
  2. 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.
  3. Check the address is TukuPay's own (tuku.money), sign in, check the request, choose your app and Sandbox or Live, and press Approve.
  4. 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

ToolDoesTry asking
tukupay_whoamiThe 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_balancesEvery wallet's balance and available amount"What's my TukuPay balance?"
tukupay_list_wallets, tukupay_get_walletYour wallets, or one"List my wallets with their ids."
tukupay_statementYour statement, with TukuPay's filters"What came in yesterday over KES 1,000?"
tukupay_list_transactions, tukupay_get_transactionPayments made through the app; one by its reference"Did order-1042 get paid?"
tukupay_collect_mpesaAn 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_linkYour payment links; make one to share"Make a KES 2,000 link for the workshop."
tukupay_transferTo 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_payoutTo 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_testYour app's webhooks"Did my last webhooks get delivered?"

What needs your PIN

ActionFrom the assistant
Reading balances, statements, payments, linksGoes 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 linkMade at once (simulated in the sandbox)
A transfer or payout within your limitsGoes 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 setWaits 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 liveYour 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 run npx -y @tukupay/mcp login again.
  • 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 seeWhyDo this
401 / "Not signed in" / "Session expired"No session yet, or the hour is upReconnect in your client, or npx -y @tukupay/mcp login
"Register an app first" on the sign-in pageYou have no app yetDevelopers → My apps → Register an app, then sign in again
402 insufficient_tokens / "Not enough Tuku AI tokens" on the sign-in pageTool calls are paid in Tuku AI tokens and the balance is too lowAdd tokens in TukuPay, then try again
403 app_not_approvedThe app is not ready for that mode (e.g. live before you went live)Choose Sandbox, or go live first
403 scope_missingThe session was not allowed that (e.g. payouts)Sign in again and tick it (login --scope "read collect payouts")
403 with a browser-based clientThe 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-inThe connector URL is wrong, or that client is not yet allowed to sign inCheck 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 appNothing 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 nowTry later; your API keys and the gateway are not affected
429 rate_limitedMore than 60 requests a minute in one sessionWait a minute
The browser does not openNo browser here, or it is blockedOpen the address the client prints, or login --device
Windows: npx not foundThe 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.