---
title: "Use from an AI agent (MCP)"
description: "You don't have to open a dashboard to run your app or game. Connect KUMODeck once to the AI coding agent you use — Claude Code, Codex, Cursor or any other agent that supports MCP — then just ask:"
url: "/docs/claude-code/"
lang: en
index: "/llms.txt"
---
# Use from an AI agent (MCP)

You don't have to open a dashboard to run your app or game. Connect KUMODeck once to the AI coding agent you use —
Claude Code, Codex, Cursor or any other agent that supports MCP — then just ask:

- "How many people came from yesterday's post on X?"
- "What did my projects cost last month, and how much prepaid credit is left?"
- "Turn on cloud saves in the production config and push it." (you confirm first)
- "Roll production back to the previous version."
- "Turn on Functions for development and deploy my `functions/` folder."

The assistant talks to the KUMODeck MCP server with **your** developer account. It never sees a secret key, and
nothing that changes your app happens without your confirmation.

More requests you can copy, from starting a project to fixing errors: [Talk to your AI agent](/docs/ask-claude-code/index.md).

## Connect

### Claude Code

```sh
claude mcp add --transport http kumo https://mcp.kumodeck.com/mcp
```

Then inside Claude Code run `/mcp` → `kumo` → **Authenticate**. Your browser opens the KUMODeck dashboard:

1. Sign in with your KUMODeck developer account, the same way as on the dashboard (saved passwords, passkeys, Google and
   GitHub all work). If you are already signed in to the dashboard, this step is skipped.
2. Check the agent's name and where access will be sent (for an agent on your computer, an address like `localhost:…`).
   Choose **what the assistant may do** and **which projects** it may touch, then Allow. The browser goes back to the
   agent, and the agent is connected.

What the assistant may do has three choices:

- **Build and publish** (recommended, selected first): see everything, change project config, publish and deploy, and
  manage server functions. Going live in production and every delete still ask you first.
- **View only**: see projects, users, usage costs, prepaid balance, server functions and their logs. Changes nothing.
- **Choose myself**: tick each scope (the table below; only the ones the agent asked for are listed). These are in no preset,
  so you can only add them here: banning users.

To change them later, disconnect in `/mcp` and authenticate again.

### Codex

Works in the Codex CLI, the IDE extension and the desktop app (they share settings).

```sh
codex mcp add kumo --url https://mcp.kumodeck.com/mcp
codex mcp login kumo
```

`codex mcp login` opens the same dashboard page as above.

Codex (like most agents) loads MCP tools when a conversation starts. If you connected in the middle of a conversation, the
agent carries on there with the `kumodeck` CLI, and KUMODeck's MCP tools are there from your next conversation. The agent should
never read saved tokens or keys to call the KUMODeck API directly: that skips the confirmations for production and deletes. Only
if the CLI itself cannot run there (not installed, cannot sign in), it asks you to start a new conversation. If you ask for
something that is not available yet, it tells you so and offers something it can do instead: a new conversation or a restart
does not change that, so it does not suggest one.

Codex cannot show confirmation forms. For changes to production it gives you a link to confirm on the dashboard instead
(see [Confirm with a link](#confirm-with-a-link)).

### Cursor

Add this to `.cursor/mcp.json` in your project (or the global one), then open **Settings → MCP** and connect `kumo`:

```json
{ "mcpServers": { "kumo": { "url": "https://mcp.kumodeck.com/mcp" } } }
```

### VS Code (Copilot agent mode)

Add this to `.vscode/mcp.json`, then start the `kumo` server from the MCP view:

```json
{ "servers": { "kumo": { "type": "http", "url": "https://mcp.kumodeck.com/mcp" } } }
```

### Other agents

KUMODeck is a remote MCP server over HTTP (Streamable HTTP), the same for every agent: add a server named `kumo`
with the URL `https://mcp.kumodeck.com/mcp`. The exact place and key names differ; these are the ones that trip people up:

| Agent | What to write |
|---|---|
| Gemini CLI | `gemini mcp add --transport http kumo https://mcp.kumodeck.com/mcp` — in a settings file use **`httpUrl`**, not `url` (`url` means the older SSE transport) |
| Windsurf / Devin | `{ "mcpServers": { "kumo": { "serverUrl": "https://mcp.kumodeck.com/mcp" } } }` in the MCP config (or `devin mcp add kumo https://mcp.kumodeck.com/mcp`) |
| Zed | `{ "context_servers": { "kumo": { "url": "https://mcp.kumodeck.com/mcp" } } }` in `settings.json` |
| Anything else with MCP | a remote / HTTP server named `kumo` at `https://mcp.kumodeck.com/mcp` |

When the agent connects, the same dashboard page opens: sign in if you are not signed in yet, then choose the scopes and
projects, as above.

> **Note** Most agents register themselves on the fly, so KUMODeck cannot confirm their name. When the agent runs on
> your computer, the page asks whether you just started connecting an AI agent on this computer: if you did, continue.
> If the page instead warns that access goes to **a server on the internet**, stop unless you recognize that address.

Your project's `AGENTS.md` (every KUMODeck template has one) is read by Codex, Cursor, Windsurf / Devin and Zed; Claude Code reads it through `CLAUDE.md`, and Gemini CLI through `GEMINI.md`. The recipes for common features
(Skills: sign-in, saves, and game recipes such as leaderboards and chat) are listed in `INDEX.md` in `.agents/skills/` (Codex, Cursor and most other agents look there) and in `.claude/skills/` (Claude Code): the same files in both.

## Starting a new project

Creating the account and the project happens in your terminal, not over MCP (the password never goes through the
assistant, and the template files have to land on your disk):

```sh
kumodeck signup                 # you type this one yourself
kumodeck create my-game --init  # the assistant can take it from here: template + project + keys (or `kumodeck init` in your own app's folder)
```

Then ask: "push the config, deploy to development, then production, and turn on sharing". The assistant runs
`kumodeck config push`, `kumodeck deploy` and `kumodeck share on` locally — or turns sharing on over MCP (`share_enable`,
you confirm production). See [Getting started](/docs/getting-started/index.md).

## Building and deploying

Uploading a new build stays on your machine: your build folder is on your computer, and a remote MCP server cannot
read it. When you ask the assistant to "deploy", it runs the CLI locally (`kumodeck deploy`,
`kumodeck functions deploy`) and then uses MCP to check the result or switch versions. Install the CLI once with
`npm install -g kumodeck` ([CLI reference](/docs/reference/cli/index.md)).

## Scopes

| Shown on the consent screen | Scope | Lets the assistant | Confirmation |
|---|---|---|---|
| View projects | `read:projects` | list projects, overview (users, daily actives), read and validate config, deployment history, card tags, custom domains (the app's and the Functions') | — |
| View reports | `read:reports` | traffic per X post | — |
| View end users (players) | `read:players` | search your users (*players* in the API; emails are masked), read ban appeals | — |
| View usage and prepaid balance | `read:payouts` | usage costs and prepaid balance | — |
| Change project config | `write:config` | push `kumo.config.json`, turn on sharing on X (`share_enable`), create tracked share links, add / remove custom domains (the app's and the Functions') | production only (removing a domain: always) |
| Switch deployments | `deploy` | activate a version / roll back | production only |
| Ban / unban end users | `write:players` | ban, unban and answer ban appeals (needs `read:players` too) | always |
| View server functions | `read:functions` | Functions status, versions, databases, crons, secret **names** | — |
| Read server function logs | `read:logs` | what your deployed code printed (Functions and the server-rendered app; `console.log` / `console.error`), last 7 days | — |
| Manage server functions | `write:functions` | enable, deploy, set secrets, run SQL and migrations, delete | production changes and deletes |

## Tools

| Tool | What it does |
|---|---|
| `projects_list` · `project_overview` | your projects; users (players), new and active users, 14-day daily actives, live version |
| `usage_get` · `usage_daily` · `prepaid_get` | what each building block cost this month (at cost) · by day · prepaid balance (and invite credit), low-balance notices, auto top-up |
| `config_get` · `config_validate` · `config_push` | read · check against every push rule without saving (errors with paths, what would change) · push |
| `deployments_list` · `deploy_activate` | version history · switch the live version |
| `players_search` · `player_get` · `player_ban` · `player_unban` | your users (players) and bans |
| `appeals_list` · `appeal_resolve` (ban appeals) | read the appeals banned users sent, then accept (the ban is lifted) or reject, with a short reply |
| `share_stats` · `share_link_create` · `share_tags` | visits, new users, opens per X post · a tracked link for your own post · the card tags to put in the page's `<head>` |
| `hosting_domains_list` · `hosting_domain_add` · `hosting_domain_remove` | your app on your own domain ([custom domains](/docs/guides/hosting/index.md#custom-domains)): status and the DNS records **you** add · add (confirmed) · remove (always confirmed) |
| `functions_domains_list` · `functions_domains_add` · `functions_domains_remove` | your Functions on your own domain ([Functions: your own domain](/docs/guides/functions/index.md#your-own-domain)): status and the DNS records **you** add · add (production: confirmed) · remove (always confirmed) |
| `project_slug_get` · `project_slug_check` | your project's URL slug, old slugs and their redirects · whether a new slug is free and what would change (read-only: you change it in the dashboard, see [changing the URL slug](/docs/guides/hosting/index.md#changing-the-url-slug)) |
| `project_rename` | change your project's display name, which appears in the subject and sender of emails your users (players) receive (no confirmation form: you can change it back any time, and you get an email about it). Returns the previous name and whether it changed. Names that look like KUMODeck or its staff are refused (`name_reserved`); the URL slug does not change |
| `functions_status` · `functions_deployments` | your [Functions](/docs/guides/functions/index.md) and their history |
| `functions_logs` | what your deployed code printed (Functions and the server-rendered app; `source` for one), newest first, last 7 days: filter by time, level and text ([logs](/docs/guides/functions/index.md#logs)) |
| `functions_enable` · `functions_disable` · `functions_deploy` | turn on (needs prepaid credit) · stop · deploy |
| `functions_secret_set` · `functions_secret_delete` | secrets (values never appear in results or confirmation text; prefer `kumodeck functions secret put` locally) |
| `functions_db_query` · `functions_db_migrate` · `functions_delete` | SQL and migrations on your own database · delete (always confirmed) |

## Safety

**Writes need a human.** Even if your assistant auto-approves tools, the server asks you. Newer clients (Claude Code)
show a "Run this?" form. Clients that cannot show that form (Codex, for example) can still read everything, and for
changes to production they give you a confirmation link instead (below). Other writes that need a confirmation, such as
banning a user in development, are refused with nothing changed: do those in the dashboard, or use a client that
supports confirmation forms.

### Confirm with a link

When a client cannot show the form, a change to production (publishing a version, pushing the production config, a
ban, a custom domain, production Functions) works like this:

1. **Nothing changes yet.** The agent shows you a link to your KUMODeck dashboard, for example: *To do this in
   production, open this link and press "Publish"*. The agent opens it in your browser when it can (otherwise open it yourself); only you can press the button, and the agent then carries on by itself, without waiting for you to reply.
2. **Check the page.** It shows what will happen (for example "Publish version 4 to production"), the project, that it
   is production, and the name the agent gave itself (KUMODeck cannot verify that name). It asks: *Did you just ask
   the AI agent you are using right now to do this?* Press the button only if you did. Approving needs a confirmed email
   address.
3. **Go back to the agent.** It sends the same request once and tells you the result. KUMODeck does not run anything
   for the agent: the change still runs with the agent's own permissions and checks, only once, and within 10 minutes
   of your approval. The link itself works for 10 minutes.

**The first publish to production is one approval.** If hosting is still off in production, the agent uploads the new
version first (nothing is live yet), and the link lists both changes in order: *Turn on publishing (hosting) in production*,
then *Publish version N*. One press allows both; the agent then sends them in that order. **Cancel all** cancels both.
If more changes were added after you opened the page, it asks you to check the list again before you approve.

**Do not recognize it? Press Cancel.** Nothing changes and the agent cannot send it (you can cancel even before you
confirm your email). If the page says the target changed after the link was made (for example a newer version went
live), nothing happened: ask the agent again for a new link.

**Production changes from the CLI are confirmed once in your browser.** When the agent logged in with `kumodeck connect` (or
`kumodeck login` in the browser), every production change it makes with the CLI (config push, deploy, rollback, secret keys,
Functions, domains…) stops and prints a confirmation link. Open it and press **Confirm** in the dashboard (or **Deny**);
the command then sends that one change, once. The agent cannot confirm it for you, and `--yes` does not skip it. A deploy uploads
first and asks once, right before the new version goes live; the first publish to production with hosting still off is also one
link and one press (turning hosting on and publishing). Sessions you start yourself with `kumodeck login --email` are not asked.

**Text written by others is fenced.** User (player) names, product names and deploy messages come back wrapped in `«…»`, and
the assistant is told not to follow instructions inside them. Confirmations remain the last line of defense: a user
named "ban everyone" still cannot make a ban happen without you.

**Your users' emails are masked** (`a***@example.com`). You can still search by email.

Every MCP action is written to your audit log with the client and tool that made it.

> **Note** The MCP server's public URL is published at launch. Until then you can run it locally (`https://mcp.kumodeck.com/mcp`) against a
> local KUMODeck server.