Kumoda as an MCP server
Connect your own AI (Claude Desktop, Claude Code, Cursor, ChatGPT) to your workspace, read only, with a token you can revoke.
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?".
It can only look
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 under Integrations, which is the other direction: your agents using someone else's tools.
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
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.
{
"mcpServers": {
"kumoda": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://agents.kumoda.io/mcp", "--header", "Authorization:${KUMODA_AUTH}"],
"env": { "KUMODA_AUTH": "Bearer YOUR_TOKEN" }
}
}
}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
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). 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
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). 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.