# Agents (/docs/agents) An agent is a job description plus what it is allowed to know. You write what it is for and how it should behave, give it documents to answer from, and choose a model. Kumoda runs it whenever a customer writes on a channel you connected. ## Starting points [#starting-points] Open **Agents** to see your agents, or **Playbooks** for ready-made ones. A playbook opens the agent builder with the agent already filled in, and you can edit anything. The starting points are: | Playbook | What it does, as the app describes it | | --- | --- | | WhatsApp enquiry responder | Answers common service questions from your documents and asks for missing details. | | Follow-up drafter | You paste an enquiry; it drafts the reply and the next follow-up. | | Payment reminder drafter | You paste an overdue invoice; it drafts a polite reminder, firmer each time. | | Support reply drafter | You paste a customer message; it drafts a clear, kind reply. | | Handover assistant | You describe how you do something; it turns it into steps your team can follow. | | Writing partner | Drafts and tightens your messages, posts and emails in your voice. | | Offer sharpener | Pushes on your offer: who it is for, the promise, the price, what is unclear. | | Start from blank | Write your own instructions. | The [Quickstart](/docs/quickstart) uses the first one. ## The builder [#the-builder] The builder has five steps: **Purpose**, **Identity**, **Knowledge**, **Tools** and **Publish**. Changes are saved as a draft as you go. ### Purpose [#purpose] One or two sentences on what the agent is for. It helps you and your team remember its job, and Flow and your other agents read it to know when to ask this agent (see [Flow](/docs/flow)). ### Identity: names, model and instructions [#identity-names-model-and-instructions] - **Internal name**: only your team sees it. - **Customer-facing name**: shown at the top of the chat window. Optional. - **Opening message**: what the agent says first. - **Instructions**: up to 4,000 characters. Write who the agent is, what it answers, and what it always does. - **Rules it always follows**: short rules, up to 12, for example "Never state a refund amount". Rules are for the things that must never go wrong. Kumoda also tells every agent to treat the results of tools as data, not as instructions. ### Models [#models] Choose a provider, then a model. Each model card shows bars for speed, quality and cost (for cost, more bars means pricier). The Anthropic models offered are: | Model | Described in the app as | | --- | --- | | Haiku 5.5 | Fast and light. Good for simple, repeated questions. | | Sonnet 5.5 | The all-round choice for most agents. Marked as recommended. | | Opus 5.5 | The strongest. For hard judgement, and the priciest. | Which models you can pick depends on your plan: the builder shows what your plan includes. Other providers are listed too, and their models can be picked once Kumoda has that provider connected. You can change the model at any time, and lighter models use fewer credits. See [Plans, credits and billing](/docs/plans-and-credits). ### Knowledge: documents [#knowledge-documents] Knowledge sources are what the agent is allowed to say. It searches them for factual questions and answers in its own words. If nothing matches, it says it does not have that to hand. Without any sources, the agent answers from its instructions alone. You can add a source three ways: - **Paste text**: a policy, FAQ or price list, up to about 200,000 characters. - **Web address**: a public page or PDF. The address must start with `https://`. You can have Kumoda read it again later to pick up changes. - **File**: PDF, Word (`.docx`), text, Markdown, CSV, JSON or HTML, up to 4 MB. A scanned PDF (pictures of pages) has no text to read. You can edit the text of a source you pasted, and the agent answers from the new text straight away. Removing a source means the agent no longer answers from it. Search is by shared words. Finding a passage that says the same thing in other words needs a setting on the Kumoda platform, which is shown in the app when it is not on yet. ### Knowledge: skills [#knowledge-skills] A skill is a procedure for a particular job, such as handling a refund or a booking. The agent reads only each skill's name and when to use it, and opens the steps when a question calls for them. Each skill has a **name**, **when to use it** (one sentence, up to 300 characters) and **steps** (up to 8,000 characters). An agent can have up to 10 skills. ### Knowledge: memory [#knowledge-memory] Memory is what the agent keeps about each person it talks to, such as a customer on WhatsApp. Each person has their own memory, and it is never shared between people or agents. - **Recent messages**: how much of the conversation the agent sees: nothing, or the last 5, 10 (the usual), 20 or 30 messages. - **Keep a note about the person**: the agent writes down their name, what they want and what was promised, and reads it next time. This uses a little more of your credits on each message. - **Find older messages by meaning**: lets the agent find something said long ago. It is available only when the platform has it switched on. If long-term memory is not switched on for the platform, the agent sees only the recent messages it is handed, and the app says so. ### Knowledge: helpers and message screening [#knowledge-helpers-and-message-screening] - **Helpers**: other agents in the same workspace this one may ask for help with part of a question, up to three. What a helper uses is billed to your credits like any answer. - **Screen messages**: checks each message for attempts to talk the agent out of its rules. A message that tells the agent to ignore its instructions or reveal them is not answered, and the person gets a polite refusal. It adds a small check to every message (about a tenth of a cent of your credits). If the check itself cannot run, the message is still answered, so a problem with it never leaves a customer without a reply. ### Tools [#tools] Tools let an agent look something up or do something. See [Tools and connections](/docs/tools-and-connections). ## Test before you publish [#test-before-you-publish] Ask the agent what a real customer would, in the preview on the builder, and read the answers and the steps it took. A preview is a real model call and uses your credits. Nothing is sent to anyone. You can also save questions as **Tests**, with what a good answer does. Run them against the saved draft before you publish a change. A member can keep up to five tests per agent, and each run uses credits. ## Publish, pause and versions [#publish-pause-and-versions] The last step checks that the agent has a name, written instructions, a test in the preview, and at least one rule. **Go live** (or **Publish version N** after the first time) makes that version the one other systems get when they call the agent. It does not message anyone. After that you can keep editing. Changes are tried in the preview and reach other systems only when you publish again. Each publish is a numbered version with an optional note, and **Restore** puts an older version back as a new one, so nothing is lost. On the agent's page you can **Pause** and **Resume** it. A draft agent has **Turn on**. An agent's status (draft, live or paused) is separate from its channels: to stop customers being answered on a channel, use the **Answer on** switch for that channel under **Channels**, which pauses it. Deleting an agent removes the agent and its versions, and its past runs stay in the list. The agent's page also shows its last seven days (runs, success rate, typical time, estimated cost), its recent runs, and **Run automatically**, which asks it the same question on a timetable. Anything an agent wants to change waits for your approval. ## Handover to a person [#handover-to-a-person] On a customer chat (WhatsApp, the website chat window or the API) every agent has one tool, `request_a_person`. The agent calls it when the customer asks for a person, is upset, says the matter is urgent, or when it cannot help or is not sure. When it does: 1. The conversation becomes yours. The agent stays out of it until you hand it back. 2. The reason is recorded, and shown in **Conversations** as "Needs you". 3. You are emailed, and so is everyone else who works the workspace (its Admins and Members), unless each has turned handover alerts off in their own profile. If you have named who handles the channel, only they are alerted (and you, when nobody has taken the chat), and if the conversation is already assigned to someone, the alert goes to that person. 4. The agent tells the customer plainly that a person will reply. In **Conversations** you can **Take over** at any time (without waiting for a handover), answer as yourself, **Hand back to agent**, **Resolve** and **Reopen**. A Viewer can read a conversation but not answer it. See [Team and workspaces](/docs/team). Two more things to know: - On the WhatsApp quick start, if you type in a chat yourself, the agent stays quiet in that chat for eight hours (or until you hand it back). - On the official WhatsApp connection, Meta does not tell Kumoda when you reply from your own phone, so the agent cannot step back by itself. Pause the channel, or take over in **Conversations**. When your credits run out, a customer who writes gets one short note that a person will reply, and the conversation is handed to you. See [Plans, credits and billing](/docs/plans-and-credits). # API reference (/docs/api-reference) Kumoda has one API you build on: the **API channel**. Your own system sends a customer's message to one of your agents and reads the reply. It is the same conversation as on WhatsApp or the website chat window, with the same credits and the same handover to a person. The OpenAPI file is at [/openapi.json](/openapi.json). Import it into Postman, Insomnia or any OpenAPI tool. The API channel is for servers. It gives no browser (CORS) access, so call it from your backend, not from a web page. To put a chat on a web page, use the [website chat window](/docs/channels#website-chat-window). ## Set it up [#set-it-up] Create the connection in the app: **Channels**, **Add channel**, **API**, choose the agent, **Create the API connection** (see [Channels](/docs/channels#api-channel)). You get two things: - the **address**, which has the form `https://agents.kumoda.io/api/v1/agents//messages`, where `` is the letter `a` and 24 lowercase hex characters, and - the **secret**, which starts with `ksk_`. It is shown only once and only a hash is kept. **New secret** replaces it, and the old one stops working at once. Every call carries the secret as a bearer token: `Authorization: Bearer ksk_…`. A wrong key and a wrong secret get the same answer, so neither can be guessed from it. An agent has one API connection, and an account can have up to 10. A paused connection refuses new messages (503). ## Send a message [#send-a-message] `POST /api/v1/agents//messages` with a JSON body. | Field | Required | What it is | | --- | :---: | --- | | `contact` | yes | Your own id for the customer: 3 to 60 letters, numbers, dots, dashes, colons or underscores. Each contact is one conversation. | | `text` | yes | The customer's message. Over 4,000 characters is refused (413). Only the first 1,500 characters are given to the agent. | | `name` | no | The customer's name, up to 80 characters. | | `email` | no | The customer's email. Ignored if it is not a valid address. | | `phone` | no | The customer's phone number, up to 30 characters. Only digits, `+`, spaces, brackets and dashes are kept. | | `messageId` | no | Your id for this message (up to 64 letters, numbers, dots, dashes, colons or underscores). Sending the same one again is not answered twice, so a retry is safe. | | `wait` | no | Seconds to wait for the reply, up to 25. The default is 20. Use `0` to return straight away and read the reply later. | Give an `email` or `phone` and the customer becomes a contact in Kumoda. ```bash curl -X POST https://agents.kumoda.io/api/v1/agents/YOUR_KEY/messages \ -H "Authorization: Bearer YOUR_SECRET" -H "Content-Type: application/json" \ -d '{"contact":"customer-123","text":"Hi, are you open today?","name":"Ada","email":"ada@example.com"}' ``` The message is saved before the call answers. The answer is a JSON object with a `status`: | `status` | Meaning | | --- | --- | | `replied` | The reply is in `reply`. `from` says who wrote it (`agent` or `human`), and `id` is its message id. | | `pending` | No reply yet (the wait ran out). Read it with `GET`. | | `duplicate` | This `messageId` was already sent. Nothing new was saved. | | `with_a_person` | A person has taken the conversation over, so the agent will not answer. | ```json { "status": "replied", "reply": "Yes, we are open until 6pm today.", "from": "agent", "id": 1042 } ``` ## Read a conversation [#read-a-conversation] `GET /api/v1/agents//messages?contact=customer-123&after=0` Returns the contact's messages after a message id, oldest first, up to 100. Pass the largest `id` you have seen as `after` to read only what is new. ```json { "messages": [ { "id": 1041, "from": "customer", "text": "Hi, are you open today?", "at": "2026-11-12T09:30:02.114Z" }, { "id": 1042, "from": "agent", "text": "Yes, we are open until 6pm today.", "at": "2026-11-12T09:30:05.870Z" } ] } ``` `from` is `customer`, `agent` or `human` (a person from your team). ## Errors and limits [#errors-and-limits] Errors are a JSON object with a message: `{ "error": "…" }`. | Status | When | | --- | --- | | 400 | A field is wrong or missing (for example `contact`, `text`, `messageId`), or the body is not JSON. | | 401 | The key or the secret is wrong. | | 404 | The address is not an API channel address. | | 405 | A method other than `POST` and `GET`. | | 413 | The text is over 4,000 characters, or the request body is over 16,000 bytes. | | 429 | More than 120 requests a minute on this connection (sending and reading share it). | | 503 | The connection is paused or not connected. | Beyond these: - Every reply uses your credits. When credits run out, the agent stops answering and a short note goes to the customer (see [Plans, credits and billing](/docs/plans-and-credits)). - Each conversation is answered at most 6 times a minute and 150 times a day. After that, messages are saved but not answered, and the channel shows a note. - You can take over any conversation from **Conversations**. While a person has it, `POST` answers with `with_a_person`. ## The website chat window's endpoints [#the-website-chat-windows-endpoints] The chat window is one small script that you paste into your site (see [Channels](/docs/channels#website-chat-window)). It talks to these routes, which are listed here so you can see what it does. They are for that script, and you do not need to call them yourself. | Route | What it does | | --- | --- | | `GET /widget.js` | The script itself. | | `GET /widget//config` | The window's title, greeting, colour, whether it asks for a name, and whether it is online. Public: nothing secret is in it. | | `POST /widget//messages` | A visitor wrote. Takes `visitor` (a random 32-character hex id the script keeps in the visitor's browser), `text` (up to 1,000 characters), and optionally `name`, `email` and `phone`. Answers `{ "ok": true }`. | | `GET /widget//messages?visitor=…&after=…` | The visitor's messages after an id, each `from` `visitor`, `team` or `agent`, with `human` (a person has the chat) and `online`. | The `` here is a letter `w` and 24 hex characters. If you list **Websites that may show it** in the window's settings, a request from any other website is refused (403). A paused window answers 503. Visitors are limited by address and by conversation, and a window has an hourly cap on messages. The numbers are kept inside the platform and may change, so build on the API channel above if you need to send messages yourself. # Channels (/docs/channels) A channel is where customers reach an agent. Open **Channels** and choose **Add channel**, or open an agent and add one there. Each channel is answered by one agent, and you can give a channel to another agent at any time from the list on the **Channels** page. All channels share the same behaviour: - Every answer uses your credits, and when credits run out the agent stops answering (see [Plans, credits and billing](/docs/plans-and-credits)). - Every conversation shows under **Conversations**, and you can take over any of them (see [Agents](/docs/agents#handover-to-a-person)). - The **Answer on** switch next to a channel pauses it. A paused channel does not answer. - Each conversation is answered at most 6 times a minute and 150 times a day. Beyond that, messages are saved but not answered, and the channel shows a note. | Channel | Good for | You need | | --- | --- | --- | | WhatsApp, quick start | Trying it in a minute, with any number | A phone with WhatsApp | | WhatsApp, official | Staying within WhatsApp's terms | A Meta Business account and a number registered for the platform | | Website chat window | Customers on your site | Access to paste one line into your pages | | API | Your own app, backend or form | A server that can make HTTPS requests | ## WhatsApp [#whatsapp] Choose how to connect. You can switch later: disconnect one and connect the other. If your plan does not include a WhatsApp number, the WhatsApp card says so and offers **See plans**. The number of WhatsApp numbers is set by your plan; the website chat window and the API do not count against it. ### Quick start (scan a code) [#quick-start-scan-a-code] Scan a code to link a number, like WhatsApp Web. It works for any number, including one that has never been verified as a business. WhatsApp can restrict numbers that send automated messages. Use a number you can afford to lose, not your only one. On the agent's WhatsApp card, or under **Channels**, choose **Quick start**, then **Connect a number**. On your phone open WhatsApp, then **Settings**, **Linked devices**, **Link a device**, and scan the code. You can link with a phone number instead: Kumoda shows a pairing code to enter. The code refreshes every few seconds, and the page notices when the scan works. Send a message to your number from another phone. The reply, and the conversation, appear in the app. What to know: - It answers one-to-one chats only, never groups. - If you type in a chat yourself, the agent stays quiet in that chat for eight hours, or until you hand the chat back. - You can set the name, about line and photo customers see from the number's card. WhatsApp does not review these on a number linked this way. - **Change connection key** replaces the secret in the address WhatsApp reports to. Use it if you think that address was seen by someone else. Messages keep arriving. - **Pause** stops answering; **Disconnect** removes the link. ### Official WhatsApp Business (your own Meta app) [#official-whatsapp-business-your-own-meta-app] This runs through your own Meta WhatsApp Business account, so your messages go through Meta's WhatsApp Business Platform under your account. It takes longer to set up: you need a Meta Business account and a number registered for the platform. Check Meta's current rules about using the same number in the WhatsApp phone app. **1. Connect in Kumoda.** In your Meta app at developers.facebook.com, open **WhatsApp**, then **API setup**. In Kumoda choose **Official WhatsApp Business** and fill in: | Field | Where to find it | | --- | --- | | Phone number ID | The long number under API setup, next to your phone number. Digits only. | | Access token | A permanent token from a Meta system user with the `whatsapp_business_messaging` permission. A temporary token expires in a day. | | App secret | In your Meta app, **App settings**, **Basic**. Kumoda uses it to check that a message really came from Meta. | | WhatsApp Business Account ID (optional) | In WhatsApp Manager, next to your account name. Add it now, or later from a conversation, to send template messages after 24 hours. | Choose **Connect with Meta**. Meta checks the details before anything is saved. The token and secret are encrypted and never shown again. **2. One more step, in your Meta app.** Kumoda then shows a **Callback URL** and a **Verify token**: In your app at developers.facebook.com, open **WhatsApp**, then **Configuration**. Under **Webhook** choose **Edit**, and paste the Callback URL and the Verify token. Meta checks them as you save. Subscribe to the **messages** field. Send a message to your number from another phone. Replies appear in the app. The verify token is shown only once. If you lose it, use **New verify token** to get another. What to know: - WhatsApp's 24-hour rule applies. You can write to a customer yourself within 24 hours of their last message. After that the conversation shows **Template needed**, and you can send an approved template message if you added your WhatsApp Business Account ID. - Meta does not tell Kumoda when you reply from your own app, so the agent cannot step back by itself. **Pause** the channel when you want to take over, or take over in **Conversations**. - The name and photo customers see are set in Meta's WhatsApp Manager, where Meta reviews them. - If Meta stops accepting the token (it may have expired or been revoked), Kumoda says so. Disconnect, then connect again with a new permanent token. ## Website chat window [#website-chat-window] A bubble on your website that opens a chat with the agent. It uses the same conversations, credits and handover as WhatsApp. Under **Channels**, choose **Add channel**, then **Website chat**, and pick the agent. Set how it looks and who may use it: - **Title** (up to 40 characters), **Colour**, and the **First message the visitor sees** (up to 200 characters). - **Websites that may show it**: one address per line, like `https://yourshop.com`. Leave it empty to allow any site. Addresses must start with `https://` (plain `http://` is accepted only for `localhost`), and you can list up to 10. - **Ask for the visitor's name first**. Choose **Create the chat window**, then copy the line Kumoda shows and paste it just before `` on every page where the chat should appear. It looks like this, with your own key: ```html ``` You can **Save** changed settings, **Pause** the window (it is hidden from visitors), or **Remove** it, which removes its conversations too. The window remembers a random visitor id in the visitor's browser, so a visitor's conversation continues when they come back. A visitor can only reach the agent you chose. ## API channel [#api-channel] Lets your own system (a website backend, an app, a form) send a customer's message to an agent and read the reply. It uses the same conversations, credits and handover as WhatsApp. Under **Channels**, choose **Add channel**, then **API**, pick the agent, and choose **Create the API connection**. Copy the **Secret** now. It is shown only once, and only a hash of it is kept. If you lose it, use **New secret**: the old one stops working at once. Send messages to the **Address** shown, which looks like `https://agents.kumoda.io/api/v1/agents/YOUR_KEY/messages`, with the secret as a bearer token: ```bash curl -X POST https://agents.kumoda.io/api/v1/agents/YOUR_KEY/messages \ -H "Authorization: Bearer YOUR_SECRET" -H "Content-Type: application/json" \ -d '{"contact":"customer-123","text":"Hi, are you open today?","name":"Ada","email":"ada@example.com"}' ``` An agent has one API connection, and an account can have up to 10. A paused connection refuses messages. The API is for servers: browsers cannot call it directly. Every field, the replies and the limits are in the [API reference](/docs/api-reference). # Flow (/docs/flow) Flow is where you ask about your business and see what is waiting for you. It reads your workspace (what needs you, the pipeline, recent contacts) and can put a question to your own agents. Name one of your agents with `@` to ask it directly. Flow cannot approve anything, message a customer or change data. Whatever is waiting for you comes back as a list with **Approve** and **Reject** buttons, so a decision is never left to what a model was told. Each answer from Flow uses credits, like an agent run. ## Who can use it [#who-can-use-it] Flow is for the **owner** of a workspace and the **Admins** who run it for them. Other roles see a note saying so. Flow is part of the paid plans. On a plan without it, the Flow page shows an invitation to upgrade instead, and the phone link and briefing settings below are not shown. Which plans include Flow is set per plan: see [Plans, credits and billing](/docs/plans-and-credits). ## The page and the sidebar chat [#the-page-and-the-sidebar-chat] Open **Flow** in the **Workspace** section of the menu. The page has: - **Needs you**: approvals waiting for you (a tool call a customer's message led to, or a workflow waiting for a yes), each with its six-character code and **Approve** and **Reject** buttons, and a count of chats an agent handed over to a person (with a button to open **Conversations**). - **Reach Flow on your phone** and **Daily briefing** (below). - **Ask Flow**: a chat box. It suggests a few questions to start, and you can ask your own, such as what needs you, or how the pipeline is doing, or `@agent` followed by a question. If an agent has no instructions, documents, skills or tools yet, the page says Flow cannot ask it and what to add. On every other workspace page, an **Ask Flow** button floats in the bottom corner. It opens Flow as a sidebar, so you can ask without leaving what you were doing. You can also open it with Ctrl+J (Cmd+J on a Mac), close it with Esc, and choose the icon in its header to open Flow as a full page. ## Flow on your phone [#flow-on-your-phone] Link WhatsApp or Telegram once, then ask Flow about your business from there and answer approvals with a reply. On the Flow page, under **Reach Flow on your phone**, choose **Link WhatsApp** or **Link Telegram**. (Each button appears only when that way of reaching Flow is switched on for the platform.) Kumoda shows a one-time code and what to do with it. The code works once, for 15 minutes. Send it from the phone you want to link. The page notices when it is used. Ask Flow things in that chat, such as what needs you. To decide an approval, reply `approve` or `reject` with the six-character code, for example `approve 3fa91c`. The whole message must be that command. Who is talking is settled by the link, not by what a message says. Only the phone that sends your code is linked, and a chat that is not linked gets one fixed reply and nothing else. A link ends when its person stops being the owner or an Admin of the workspace. Kumoda has one Flow number on WhatsApp and one Telegram bot, which every owner uses. ## Daily briefing [#daily-briefing] Each morning, Kumoda can send you one short message: what happened in the last 24 hours, what needs you (with the codes to approve from your phone), and anything that is wrong. It is free. It is written from your records without asking a model, so it says only what is in them. A briefing covers: - **Conversations**: how many there were, how many your agents handled on their own, how many messages came in and went out, and how long first answers typically took. - **New contacts** and the **pipeline**: how many contacts sit in each stage. - **Needs you**: chats handed to you and approvals waiting, each with its code. - **Heads up**: failed agent runs, a channel that needs attention, and credits that are low or gone. - On a quiet day it says so. In the **Daily briefing** card on the Flow page you can switch it on or off, choose the **hour** (it is set in Lagos time, UTC+1), and choose how it arrives: **Email**, **WhatsApp**, or both. WhatsApp needs your WhatsApp number, with the country code, saved in your profile, and a connected WhatsApp number (a linked Flow chat is used first, when you have one). **See today's briefing** shows it on the page, and **Send me one now** sends one straight away. Each briefing is sent once a day. To stop the emails altogether, turn off the briefing email in your profile. # Welcome to Kumoda (/docs) Kumoda is for owner-led businesses. You build an **agent**, give it your own documents, and connect it to a channel where your customers already write: WhatsApp, a chat window on your website, or an API. The agent answers from what you gave it, and hands the conversation to a person when it should. You can read every conversation and take over any of them. These pages describe what Kumoda does today. They are written from the product itself, and anything the product does not do is left out. ## Start here [#start-here] Sign up, build an agent, connect WhatsApp and test it. Instructions, documents, skills, models, publishing and handover. WhatsApp, the website chat window and the API channel. Web tools, webhooks, MCP servers, and the approvals that keep you in control. ## Running a workspace [#running-a-workspace] Your chief of staff: a page, a sidebar chat, your phone and a daily briefing. Owner, Admin, Member and Viewer, seats, the admin log and two-step sign-in. What a credit is, credit packs, and what happens when credits run out. What is stored, which cookies are used, and the optional campaign tag choice. ## Connecting other systems [#connecting-other-systems] Let Claude Desktop, Claude Code, Cursor or ChatGPT look at your workspace, read only. Send a customer message and read the reply from your own system. ## The ideas behind it [#the-ideas-behind-it] - **Agents answer from your documents.** If the answer is not in what you gave it, the agent says it does not have that to hand. - **Nothing changes without you.** A tool that only reads can run on its own. A tool that changes something outside Kumoda waits for your approval, each time. - **You can always step in.** Take over any conversation, hand it back, or pause an agent or a channel. - **Costs are visible.** Every answer uses credits, and you can see what is left under Billing. These docs are also published as [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt), and every page is available as Markdown by adding `.md` to its address. # Kumoda as an MCP server (/docs/mcp-server) Kumoda has its own MCP server for you. Connect your own AI client to it and ask about your conversations, contacts, pipeline and agents in plain words: "who is still waiting for an answer?", "what did the support agent do today?". This server is read only. It has no tool that sends a message, changes something, deletes something or touches billing. A connection that could also act (adding a note, moving a deal, pausing an agent, each waiting for your approval) is shown in the app as "Read and act", marked **Pro and up, coming later**. It is not available yet, and Kumoda refuses a token for it. This is different from [MCP servers](/docs/tools-and-connections#mcp-servers) under **Integrations**, which is the other direction: your agents using someone else's tools. ## Make a token [#make-a-token] Only the **Owner** of a workspace, or an **Admin**, can make, renew or revoke a connection. Everyone else sees a note asking them to ask one of those two. Open **Integrations** and choose the **MCP clients** tab. The address your AI connects to is shown at the top. It is the same address for every workspace, and by default it is `https://agents.kumoda.io/mcp`. The token you make decides which workspace it opens. If the tab says connecting your own AI is not switched on for the platform yet, Kumoda has not had its latest database update (migration 119) applied. Nothing is wrong with your account. Under **Make a connection**, give it a **Name** so you can tell it apart later, such as "Claude Desktop on my laptop" (up to 60 letters, numbers and a few marks). Leave **Read only** selected, and choose **Make a token**. Copy the token now. It is shown only once and cannot be shown again. If you lose it, revoke it and make a new one. The page also shows the setup text for each AI with your token filled in. Set up your AI using the matching tab below. A token looks like `kmd_mcp_` followed by 43 letters, numbers, dashes and underscores. Kumoda keeps only a hash of it, plus the first characters (so you can recognise it in the list). A workspace can have up to 10 working tokens. ## Set up your AI [#set-up-your-ai] Replace `YOUR_TOKEN` with your token, and the address with the one the app shows if it differs. Open **Settings**, **Developer**, **Edit Config**, and add this to `claude_desktop_config.json`. It needs Node.js installed. Restart Claude Desktop afterwards. ```json { "mcpServers": { "kumoda": { "command": "npx", "args": ["-y", "mcp-remote", "https://agents.kumoda.io/mcp", "--header", "Authorization:${KUMODA_AUTH}"], "env": { "KUMODA_AUTH": "Bearer YOUR_TOKEN" } } } } ``` Run this once in your terminal. ```bash claude mcp add --transport http kumoda https://agents.kumoda.io/mcp --header "Authorization: Bearer YOUR_TOKEN" ``` Add this to `~/.cursor/mcp.json` (for every project) or `.cursor/mcp.json` (for one). ```json { "mcpServers": { "kumoda": { "url": "https://agents.kumoda.io/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` In ChatGPT, open **Settings**, **Connectors**, **Advanced**, turn on **Developer mode**, then create a connector. Paste this as its MCP server address and choose no authentication, because the token is in the address. The menu names change from time to time. ```text https://agents.kumoda.io/mcp?token=YOUR_TOKEN ``` This address contains your token, so treat it like a password. Do not share it or paste it anywhere public. A web server or proxy between you and Kumoda might log the address. Revoke the token in Kumoda if it leaks. Any other MCP client that speaks the plain HTTP form of the protocol ("streamable HTTP") can connect to the same address with an `Authorization: Bearer YOUR_TOKEN` header. The server accepts `POST` only, and speaks protocol versions `2025-06-18`, `2025-03-26` and `2024-11-05`. ## What your AI can look at [#what-your-ai-can-look-at] There are ten tools. All of them only read, and each says so to the client (`readOnlyHint`). What customers wrote is passed on as information to report on, never as instructions for your AI to follow. | Tool | What it gives your AI | Options | | --- | --- | --- | | `list_conversations` | Customer conversations, newest first: who, on which channel, who is answering (an agent or a person), and when they last wrote | `state`: `open` (default), `resolved`, `with_person` or `all`; `limit` up to 50 (default 20) | | `get_conversation` | One conversation's latest messages, oldest first, each with who wrote it (customer, agent or person) and when | `conversation_id` (from the two tools around it); `limit` up to 50 (default 30) | | `find_unanswered_conversations` | Open conversations where the customer wrote last and nobody has answered yet, longest waiting first | `hours` to look back, 1 to 168 (default 48); `limit` up to 50 (default 20) | | `search_contacts` | Contacts matching part of a name, email, phone number or company, most recently active first | `query`; `limit` up to 25 (default 10) | | `get_contact` | One contact with their pipeline stage and latest timeline (enquiries, notes, stage changes) | `contact_id` | | `get_pipeline` | The pipeline stages with how many contacts sit in each, and the contacts in one stage if you name it | `stage` (optional); `limit` up to 25 (default 10) | | `list_agents` | Your agents: name, whether each is live, what it is for and the model it uses. Instructions and documents are not shown | none | | `get_agent_runs` | The latest runs of your agents: what each was asked, whether it worked, what it cost in credits. Test runs are left out | `agent_id` (optional); `limit` up to 30 (default 10) | | `get_credits` | The plan, credits used and credits left, when they renew, and how many agents and channels the plan allows. Credits belong to the account that owns the workspace, so they are shared by its workspaces | none | | `get_briefing` | Today's briefing, as you would read it in the morning (see [Flow](/docs/flow#daily-briefing)). The codes for approving from a phone are removed, so approval codes never reach an AI client | none | Contacts include the email address and phone number you hold for them. How answers are limited: - Answers are shortened (at most 12,000 characters), and individual messages are clipped. Keys and passwords found in a message are hidden before your AI sees it. - A token opens **one workspace** and nothing else. What it can read is limited to that workspace by the query itself, so an argument cannot reach another one. - The platform allows 60 requests a minute and 300 tool calls an hour for each token. If an hour's calls are used up, your AI is told to try again in the next hour. ## Keep control of a token [#keep-control-of-a-token] The list under **Your connections** shows each token's name, its first characters, whether it is **Working**, **Expired** or **Revoked**, when it was last used and when it expires. - **Revoke** stops the token at once. The AI using it stops working. You can make a new one any time. Revoking twice is harmless. - **Renew 90 days** extends a token that is still working. Tokens last 90 days unless renewed. A revoked token cannot be renewed: make a new one. - A token **also stops working** when the person who made it no longer manages the workspace: if an Admin is removed or changed to another role, the tokens they made stop working. Make a new one from an Owner or Admin account. - When an Admin makes, renews or revokes a token, it is recorded in the workspace's admin log (see [Team and workspaces](/docs/team#admin-log)). Using a token is not an Admin acting, so it is not logged there: it shows as "used" on the token instead. - Wrong tokens are refused with a message saying why (not a Kumoda token, not valid, revoked, expired, or its maker no longer manages the workspace), and an address that tries many wrong tokens in a minute is slowed down. # Plans, credits and billing (/docs/plans-and-credits) ## Where to see your numbers [#where-to-see-your-numbers] The numbers for each plan (prices, credits, agents, workspaces, WhatsApp numbers, people per workspace, models) are held in Kumoda's database and can change. These docs do not repeat them, so they cannot go out of date. To see them: - **Billing** shows your own plan: the credits left out of the total, when credits refill, how many agents the plan allows, whether the plan is active, and the next payment date. - **Plans** (on the same page, and the **See plans** buttons around the app) lists every plan with what it includes, with a **Monthly** or **Yearly** switch and a currency switch. - The public plans page on [kumoda.io/pricing](https://kumoda.io/pricing). Plans are called **Free**, **Pro** and **Business** at the time of writing. A plan sets: - how many **credits** you get, and whether they refill, - how many **agents** a workspace can have, - which **models** an agent can use, - how many **workspaces** you can own and how many **WhatsApp numbers** you can connect, - how many **people** a workspace can have (see [Team and workspaces](/docs/team)), - whether **Flow** is included (see [Flow](/docs/flow)). ## What a credit is [#what-a-credit-is] A credit is one cent of model use. 100 credits is about one US dollar of model-use allowance. It is not a fixed number of chats: usage varies with message length, how much of your documents the agent reads, and the model you choose. A lighter model uses fewer credits. Credits are used when an agent answers, and also by: - **Test runs and previews.** They are real model calls. - **Flow answers**, which are charged like an agent run. - **Helpers**, when an agent asks another agent for help. - **Message screening**, a small check on each message (about a tenth of a credit), if you turned it on. - **Keeping a note about each person**, a little more on each message, if you turned it on. The [daily briefing](/docs/flow#daily-briefing) is free: it is written from your records without asking a model. Credits belong to the account that owns the workspace, so they are shared by all of that account's workspaces. After your agents have answered a few customers, **Billing** shows the last 30 days: how many conversations, about how many credits each one cost, and roughly how many more conversations your credits cover at that pace. ## Refills and paid plans [#refills-and-paid-plans] - On **Free**, credits are one-time: they do not refill. - On a paid plan, credits refill each period, and **Billing** shows the refill date. - A paid plan is paid for one period at a time (a month, or a year at 20 percent off the twelve months). **It does not renew by itself**: you renew by paying again from **Billing** or the plans list. Kumoda emails you before the plan ends and again when it has ended. Renewing before the end adds the new period to the end of the current one. After a plan ends you are back on the Free plan until you renew, and your agents are kept. If you are already on a higher plan, buying a lower one does not take you down. - Every payment is listed under **Payments and invoices** on **Billing**, with its invoice number. You can search it and filter by status. If you paid and it is not showing, email the reference from your payment confirmation to support. ## Credit packs [#credit-packs] If you need more credits without changing your plan, **Billing** has **Need more credits?** with packs for sale. - A pack adds a number of credits, paid through the same checkout as a plan. - Pack credits last a year. They are used after your plan's own credits for the period are gone, so nothing is lost when the plan refills. On Free they add to the starting credits. - Packs are for sale only when the Kumoda team has priced and opened them, so the list under **Need more credits?** is the source of truth. ## When credits run low or run out [#when-credits-run-low-or-run-out] - When about 20 percent of your credits are left, Kumoda emails you once for that credit period. Billing also says you are running low. - When credits are gone, Kumoda emails you once more, and **your agents stop answering**. - A customer who writes after that gets one short note: *Thanks for your message. We cannot answer automatically right now, but a person will reply as soon as they can.* The conversation is handed to you, so it shows in **Conversations** as needing you, and in the [daily briefing](/docs/flow#daily-briefing) if you have it on. - Add credits by buying a pack, or renew or move up a plan. The count starts again when credits are added, so a new low or out notice can follow later. You can turn these emails off in your profile. ## Plan limits you may meet [#plan-limits-you-may-meet] - If your plan has no more agents to give, the agent builder says so and offers to upgrade. - If your plan does not include a WhatsApp number, or all of them are used, the WhatsApp card says so and offers **See plans**. The website chat window and the API do not count against it. - The agent builder tells you which models your plan includes. - Every seat in a workspace in use blocks new invitations, and a full set of workspaces turns **New workspace** into **Upgrade for more workspaces**. # Privacy and data (/docs/privacy-and-data) This page is a plain summary. The [Privacy Policy](https://app.kumoda.io/privacy) is the authoritative text, and it is what applies if the two ever differ. For the legal terms see the [Terms of Service](https://app.kumoda.io/terms) and the [Data Processing Addendum](https://app.kumoda.io/dpa). Kumoda is operated by Restart Integrated Systems Ltd. (Restart Inc.), a company based in Lagos, Nigeria. Questions about your data go to privacy@restart.ng. ## Two roles [#two-roles] - For **your account** (your name, email, plan and payments), Kumoda decides how the data is used, so Kumoda is the controller. - For **your customers' messages, your contacts and the documents you give your agents**, you decide how the data is used and Kumoda handles it for you, so you are the controller and Kumoda is the processor. The Data Processing Addendum covers that. ## What is stored [#what-is-stored] | What | Details | | --- | --- | | Your account | Name, email address, sign-in details (a password, or sign-in with Google) and a profile photo if you add one. | | Your plan and payments | Which plan you are on, credits used, and payment records and invoices. Card details are taken by the payment provider, not by Kumoda. | | What you build | Your agents' instructions, rules and skills, and the documents, pages and files you give them to answer from. | | Conversations | The messages your customers send through WhatsApp, your website chat window or the API, the replies (from an agent or from you), delivery status, and what customers give about themselves, such as a name, phone number or email address. | | Contacts | People created in your workspace from those conversations, or added by you. | | Use of the service | Which agent ran, when, how many credits it used, and technical records needed to run and protect the service, such as network addresses used to limit abuse. | Kumoda does not sell personal data, and does not use your customers' messages or your documents to train AI models. ## How long it is kept [#how-long-it-is-kept] - Your account data is kept while your account is open, and afterwards for as long as the law requires for payment and accounting records. - Conversations are kept until you delete them, or delete the agent or channel they belong to, which removes its conversations. - The detailed records of each AI run are kept for 14 days, then deleted. - When you ask for your account to be deleted, your data is deleted within 30 days. Backups can hold a copy for a short time longer, and are then overwritten. ## Who else handles it [#who-else-handles-it] Each of these handles data only to run Kumoda. - **AI model providers.** To write a reply, the text of the conversation and the parts of your documents that apply are sent to the model you or your plan choose: Anthropic, and OpenAI or Google where those models are switched on. - **Meta (WhatsApp).** If you connect the official WhatsApp Business connection, messages pass through Meta's WhatsApp Business Platform under your own Meta account. The quick start pairs a number by QR code through software Kumoda runs. - **Payments.** Flutterwave takes payments for paid plans. - **Email and messaging providers**, which deliver what Kumoda sends you. - **Hosting**, on servers Kumoda operates or rents, which hold the database and files. - **Analytics**, which Kumoda hosts itself, without advertising cookies. Some of these providers are outside Nigeria. Where personal data leaves Nigeria, Kumoda relies on the safeguards the law allows, such as contracts with the provider. ## Protections that matter day to day [#protections-that-matter-day-to-day] - Connection keys and secrets (webhook tokens, MCP server keys, the official WhatsApp token) are stored encrypted and are never shown again. - Access to your data is limited to your own account by the database itself. - Keys and passwords found in messages or in tool results are hidden before an agent or your own AI client reads them. - Agent screening of messages for attempts to take over an agent is an option you turn on per agent. See [Agents](/docs/agents). - When Kumoda's team needs to see the app as you to fix a problem you reported, an owner on the team can view it as you. Each time is recorded (who, whose account and when), and it is done only to help. ## Cookies and browser storage [#cookies-and-browser-storage] Most of what Kumoda keeps in your browser is needed for the app to work and needs no consent. There are no advertising or retargeting cookies. | What | Why | | --- | --- | | Your sign-in session | Kept in the browser's own storage so you stay signed in. | | Two small cookies on kumoda.io and its subdomains | One records whether you are signed in (so the website can show a Dashboard link), and one records whether you chose light or dark mode. Neither holds your session or personal data. This documentation site reads the light or dark choice, so it matches the app. | | Your country and currency | What you choose is saved in your browser so prices stay in your currency. For a first guess, your internet address is sent once to a country lookup service (api.country.is), which sees that address and answers with a country code. Only the country code is kept, in your browser, for 30 days. | | The chat window on a website | A random visitor id in that visitor's browser, so a conversation continues when they come back. | ### The optional campaign tag choice [#the-optional-campaign-tag-choice] The first time you visit, Kumoda asks about one optional thing: remembering where you came from. - If you tick the box, Kumoda remembers the **campaign tags** in the link you used, the **website that sent you** and the **page you landed on**. They are kept in your browser, and sent to Kumoda together with your email when you send a form, so a reply can have context. - If you do not tick it, or choose **Not now**, or close the prompt, none of this is stored or sent. **Not now** asks again after a week. - You can change your choice at any time, from the **change your cookie choice** link in the privacy policy. Clearing the site's data in your browser removes everything above. ## Analytics on these docs and on Kumoda [#analytics-on-these-docs-and-on-kumoda] Kumoda counts visits and product events with OpenPanel, hosted by Kumoda itself. It is **cookieless**: it sets no cookies. This documentation site uses the same analytics and no other tracker. Kumoda's rules for those events: no names, emails, phone numbers, company names, workspace names or message text are sent. Pages in the app are counted by route name (for example an agent page, never a workspace's name), and from a link only the campaign tags (`utm_*`) and a `ref` value are kept. ## Your rights [#your-rights] Under the Nigeria Data Protection Act and similar laws you can ask what personal data Kumoda holds about you and get a copy, ask for it to be corrected or deleted, object to or limit how it is used, and withdraw consent where Kumoda relies on it. Email privacy@restart.ng. Kumoda answers within 30 days. If you are a customer of one of Kumoda's customers, your request goes to that business, which decides about your data. You can also complain to the Nigeria Data Protection Commission. Kumoda is for businesses and is not meant for anyone under 18. # Quickstart (/docs/quickstart) This takes you from nothing to an agent answering a real message. You need a phone with WhatsApp for the last steps, and a few facts about your business. ## Sign up [#sign-up] Open [app.kumoda.io](https://app.kumoda.io) and choose **Create account**. You can sign up with an email address and a password, or with **Continue with Google**. If you used email, Kumoda may send a confirmation link first. Open it, then sign in. If the email does not arrive, the sign-in page can send a new confirmation link. ## Your workspace [#your-workspace] Every account starts with one workspace, called **My business**. A workspace keeps one business apart from another: its own agents, channels, contacts and pipeline. You can rename it, and add more if your plan allows (see [Team and workspaces](/docs/team)). You do not need to do anything here to continue. ## Build an agent with the Quick start [#build-an-agent-with-the-quick-start] On the dashboard, the **Get started** card lists five steps and ticks each one as you do it. Start with **Quick start**. (If you closed the card, the same page is at `app.kumoda.io/agents/mine/quickstart`.) Quick start asks about your business: - **Business name** and **what you do**: a sentence or two. - **Prices**, **hours and where you work**, and **how to book or what happens next**. These are optional. If you leave prices out, the agent says a person will confirm prices. - **When should it hand over to you?** It starts with "The customer asks for a person, is upset, or the matter is urgent." Change it to suit you. When you choose **Create my agent**, Kumoda makes a WhatsApp enquiry agent named after your business and saves what you wrote as its first document. It will not invent anything that is not in what you gave it. Only the owner of a workspace, or an Admin, can set up an agent. Everyone else sees a note asking them to ask the owner. Your plan also sets how many agents a workspace can have. See [Plans, credits and billing](/docs/plans-and-credits). If you want every setting instead, choose **I want the full builder instead**. The builder is covered in [Agents](/docs/agents). ## Test it [#test-it] Quick start gives you three questions a customer might ask (price, opening days, how to book). Change them to match what your customers really ask, and choose **Ask** on each. Read the answers. - If an answer is wrong, choose **Something is wrong: add or fix what it knows**, and fix the document. - Test runs use a few of your credits, like any answer. - Nothing is sent to anyone while you test. You need to ask at least one question before you can continue. ## Connect WhatsApp [#connect-whatsapp] Choose **Connect WhatsApp**, or open **Channels** and choose **Add channel**. You will be asked how to connect: - **Quick start**: scan a code on your phone, like WhatsApp Web. Ready in a minute. It is an unofficial link. - **Official WhatsApp Business**: runs through your own Meta account. It takes longer to set up. For the quick start, open WhatsApp on your phone, go to **Settings**, then **Linked devices**, then **Link a device**, and scan the code. The page notices when the scan works. The full steps, including the official option, are in [Channels](/docs/channels). If your plan does not include a WhatsApp number, the WhatsApp card says so and offers **See plans**. You can add a website chat window instead. ## Switch it on and try it [#switch-it-on-and-try-it] When you are ready, choose **Switch it on**. This marks the agent live. Once a channel is connected and not paused, it answers customer messages. To stop it answering, turn off the **Answer on** switch for that channel under **Channels**, or take over a single conversation from **Conversations**. From another phone, send a message to your WhatsApp number. The reply appears in the chat, and the conversation appears under **Conversations** (and under **Recent conversations** on the channel). When the agent hands a conversation to you, it appears under **Conversations** and you are emailed. You can take over any conversation, hand it back to the agent, or pause the agent at any time. ## What next [#what-next] Add more documents, skills and rules, and choose a model. A chat window on your website, or the API. Let the agent look things up or do things, with your approval. See what a conversation costs, and what happens at zero. # Team and workspaces (/docs/team) ## Workspaces [#workspaces] A workspace keeps one business apart from another: its own agents, channels, contacts and pipeline. Every account starts with one, called **My business**. - Switch between workspaces from the switcher in the sidebar. Choose **New workspace**, give it a name (a client or brand), and choose **Add**. When your plan has no more workspaces to give, the switcher offers **Upgrade for more workspaces** instead. - Only the workspaces you own count against your plan. Workspaces other people share with you show a role badge next to the name, and do not count. - The owner and Admins can rename a workspace. The owner can delete one (when they own at least two). Deleting removes every agent and document in it, and Kumoda refuses while an agent in it has WhatsApp connected. - Credits belong to the account that owns the workspaces, so they are shared by all of that account's workspaces. How many workspaces, agents, WhatsApp numbers and people a plan includes is set per plan. See [Plans, credits and billing](/docs/plans-and-credits). ## Roles [#roles] There are four roles. The **Owner** is the person whose account owns the workspace. The owner invites others as **Admin**, **Member** or **Viewer**. | Role | What they can do | | --- | --- | | **Owner** | Everything an Admin can do, plus who is on the team (invitations, roles, removal) and the admin log. The workspace is on the owner's plan and credits. | | **Admin** | Sets the workspace up and runs it for the owner: agents, channels, integrations, stages and contacts, plus everything a Member does. | | **Member** | Answers conversations, takes over and hands back, and updates contacts and stages. | | **Viewer** | Reads conversations and contacts. Changes nothing. | The app shows the same breakdown in a table on the team card: | What | Owner | Admin | Member | Viewer | | --- | :---: | :---: | :---: | :---: | | Read conversations, contacts and the pipeline | ✓ | ✓ | ✓ | ✓ | | Answer, take over and hand back conversations | ✓ | ✓ | ✓ | | | Add and edit contacts, move them through stages | ✓ | ✓ | ✓ | | | Create and edit agents, knowledge, skills and workflows | ✓ | ✓ | | | | Connect channels and integrations | ✓ | ✓ | | | | Change pipeline stages and agent rules | ✓ | ✓ | | | | Delete contacts, rename the workspace | ✓ | ✓ | | | The database enforces these rules; the table only describes them. An Admin acts for the owner in that workspace only: what they make belongs to the owner and uses the owner's plan and credits. Flow and Kumoda's MCP server tokens are for the owner and Admins (see [Flow](/docs/flow) and [Kumoda as an MCP server](/docs/mcp-server)). ## Seats and inviting people [#seats-and-inviting-people] Your plan sets how many people a workspace can have, you included. The team card says how many seats are used, **counting invitations that are still open**. On a plan for one person, the card suggests upgrading to bring a team in. To invite someone, open **Profile**, then **Team** (the team card for the workspace), enter their **email** and choose their **role**. Only the owner invites, changes roles and removes people. - Kumoda emails an invitation, and also shows a link you can send yourself. The link works once and expires in 7 days. - The person signs in, or creates an account, with that same email address, and accepts. - Until they accept, the invitation shows as pending. You can **Cancel** it, or wait for it to expire. - The owner can change a person's role from the list at any time, or remove them. Every seat in use blocks new invitations until you remove someone, cancel an invitation or upgrade. ## Admin log [#admin-log] The owner can see **What Admins changed**, newest first, on the team card (it appears once the workspace has an Admin). Every change an Admin makes in the workspace is listed with who made it and when. Repeats of the same change are grouped, for example "(3 times)". It covers, among others, connecting, pausing or removing a channel, adding or removing an integration, changing what an agent knows, replying to a customer, taking over, handing back or resolving a conversation, and making, renewing or revoking an MCP client token. Changes to agents, pipeline stages and contacts are recorded by the database itself. Only the owner sees the log. ## Handling conversations as a team [#handling-conversations-as-a-team] By default everyone on the team who works the workspace (the owner, Admins and Members) is alerted when an agent hands a conversation over. To change that, open the channel under **Channels**, find **Who handles this channel** (the owner and Admins see it), choose the people, and choose **Save**. Then only they are alerted, and the owner is copied when nobody has taken the chat. Tick **Assign new handovers automatically** to give each one to the chosen person with the fewest open conversations. In **Conversations**, the owner and Admins can assign a conversation to a person. A Member can **Assign to me** and **Release**. The filters show which conversations need you and which are assigned to you. ## Two-step sign-in [#two-step-sign-in] Two-step sign-in adds a code from an authenticator app (Google Authenticator, 1Password or Authy) to your password, so someone who learns your password still cannot get in. It is for your own account, and each person turns it on for themselves. Open **Profile**, then the **Security** tab, and choose **Turn on two-step sign-in**. Scan the QR code with your authenticator app. If you cannot scan it, type the key shown into the app instead. Type the 6-digit code the app shows, and choose **Confirm and turn on**. From then on, signing in (with a password or with Google) also asks for a code before you get in. To turn it off, open the same card, choose **Turn off**, and enter a current code. # Tools and connections (/docs/tools-and-connections) Out of the box an agent answers from its instructions and documents. Connections let it do more: look an order up, check a booking, send a lead to your own system. You choose what it may use, and anything that changes something outside Kumoda waits for you. Open **Integrations**. The tabs there are **Integrations**, **Web tools**, **MCP servers** and **MCP clients**. The first three are things your agents use. The last one is something else: it lets *your* AI look at Kumoda (see [Kumoda as an MCP server](/docs/mcp-server)). A tool that only reads runs when the agent asks. A tool that changes something waits for your approval, each time. Keys you give Kumoda are saved encrypted and are never shown again. ## Give an agent a connection [#give-an-agent-a-connection] A connection is made once, under **Integrations**, and then switched on for each agent that should use it. On the agent's page, open **Tools** and switch on the connections it may use. The page shows how many tools are on, and how many can change something. An account can hold up to 50 connections, and a connection can be used up to 60 times an hour. A connection's name must be unique within its workspace. ## Web tools [#web-tools] A web tool lets an agent call any service that has a web API. Under **Integrations**, **Web tools**, choose **Add a web tool** and fill in: | Field | What to put | | --- | --- | | Name | Letters, numbers and underscores, such as `order_status`. | | Method | `GET` only reads. `POST`, `PUT`, `PATCH` and `DELETE` change something, so they always ask you first. | | What it does | The agent reads this to decide when to use the tool. | | Address | Starts with `https://`. Write `{{input_name}}` where the agent's value goes, and `{{secret:NAME}}` for a key. | | Inputs | The values the agent fills in: a name, a type (text, number or yes/no) and what it is. Up to 12. | | Headers (optional) | For example `Authorization` with the value `Bearer {{secret:API_KEY}}`. Up to 12. | | Secrets (optional) | Keys the call needs. Saved encrypted, used only when the call is made, never shown again. Up to 5. | A `GET` tool that actually changes something can be marked so it asks you first. For methods other than `GET` you choose whether the inputs go in the request body as JSON. Example address: `https://api.myshop.com/orders/{{order_id}}` Use **Try it** on a web tool to make a real call with sample values. It only runs tools that read: a tool that changes something is never run from here, an agent files it for your approval. ## Webhooks [#webhooks] A webhook lets an agent send information to a system you own: a Zapier, Make or n8n flow, or your own server. Under **Integrations**, add a webhook with a **name** (letters, numbers and underscores, such as `send_lead`), an **address** (it must start with `https://`), **what it is for** (the agent reads this to decide when to use it: say what it sends and when), and an optional **token**, which is sent as a bearer token if your address expects one. The agent sends a short summary and a few name and value pairs, as JSON, with the agent's name and a timestamp. Use **Try it** to see your address answer. ## MCP servers [#mcp-servers] An MCP server publishes its own tools: a CRM, a calendar, a database, search. Connect one and your agents can use those tools. Under **Integrations**, **MCP servers**, choose **Connect an MCP server**. **Name and address.** The name is letters, numbers and underscores (such as `my_crm`, up to 30 characters), and its tools are named after it. You cannot change the name later. The address starts with `https://` and often ends in `/mcp`. Kumoda only calls public addresses on the normal https port, and the key must not be written inside the address. **How the server checks you.** Pick one: - **A key**: an API key or token. It is sent as a bearer token, unless you name another header (for example `X-Api-Key`). - **Headers**: for a server that wants several headers, or its own scheme. Up to six headers, each value encrypted. A value can be `Bearer your-key`. - **No key**: the server is open. **Check the server.** Choose **Check the server** and Kumoda connects and lists its tools before anything is saved. For each tool you choose: - **Use**: switch the tool on for your agents. - **Without asking**: let an agent use it straight away. Leave it off for anything that changes something, and each use will wait for your approval. A tool the server says only reads is marked as such. If you change the address or the key after checking, the list is asked for again, because it may have changed. **Connect.** Nothing is saved until the server answers. If you connect without checking, every tool starts on, and only the tools the server says only read run without asking. ### Change a connected server [#change-a-connected-server] Open the server's card under **MCP servers**: - **Edit** changes the address, a note on what it is for, and the key. For the key you can **keep the saved one**, send **a key**, send **headers**, or choose **no key**. The saved values are never shown, only which header they are sent in. Kumoda asks the server first, and keeps what was saved if the server refuses. - **Refresh tools** asks the server for its tools again. Tools you had already chosen keep your choices. A tool the server added since starts switched on. - Open **Tools** on the card to **Switch all on** or **Switch all off**, and to set **Use** and **Without asking** per tool (a search box appears when a server has more than six tools). The card counts how many tools are on, how many run without asking, and how many ask first. - **Remove** deletes the key, and agents linked to it stop using it. A server can offer up to 60 tools. ### Customers' messages and your connections [#customers-messages-and-your-connections] By default, only you can make an agent use a connection, when you test the agent. A message from a customer cannot cause a call. To allow it, open the connection's card, open the **Customers' WhatsApp messages** setting, and tick **Allow customers' WhatsApp messages to make the agent use it**. Kumoda asks you to confirm. In the platform, this applies to a message from a customer on any channel (WhatsApp, the website chat window or the API), not only WhatsApp. Even then, each use is filed as a request and waits for your approval (this option, **Ask me to approve each one first**, is recommended). Switching it off lets customer-triggered uses happen straight away, so anything a customer can talk the agent into will happen. ## Approvals: "Waiting for you" [#approvals-waiting-for-you] When an agent asks to use something that needs your OK, it is filed as a request instead of being done. The agent tells the customer that you have to approve it and that it has **not** been done yet. You are told straight away: - By **email**, with a link. - On **WhatsApp**, if your own number (with the country code) is in your profile. Reply `approve 3fa91c` or `reject 3fa91c`, using the six-character code in the message. The whole message must be that command, and it must come from your number. - In **Flow**, under **Needs you**, with **Approve** and **Reject** buttons (see [Flow](/docs/flow)), and in the [daily briefing](/docs/flow#daily-briefing). - Under **Integrations**, a **Waiting for you** box appears with the requests, each showing which agent asked and what it wants to do. Approving makes the call once, exactly as shown. Rejecting does nothing and sends nothing. Up to 20 requests can be waiting at a time. If more arrive, the extra ones are not filed and the agent tells the customer you will follow up. ## What is read-only [#what-is-read-only] - A web tool using `GET` (unless you marked it as changing something), and an MCP tool the server says only reads, can run without asking. - When you ask [Flow](/docs/flow) a question and it asks one of your agents, only reading tools are offered. Anything that would need approval is left out. - Kumoda's own MCP server is read-only: it cannot send, change or delete anything. See [Kumoda as an MCP server](/docs/mcp-server). ## How calls are kept safe [#how-calls-are-kept-safe] - Only `https://` addresses on the normal port, and only public addresses. The name is resolved and the address checked, and the call is made to the address that was checked. Redirects are not followed. - Replies are shortened, and keys found in a reply are hidden. What comes back from a service is treated as data, never as instructions. - Keys and tokens are saved encrypted, and used only when a call is made. - Every use shows in the agent's runs.