Connect KUMODeck to an AI

This page is for the AI. The user pasted a short text that points here; they do not need to read it. Follow the part that fits you.

First: which one are you?#

• You can run commands on the user's computer (Claude Code, Codex, Cursor or another coding agent): follow A.
• You are Claude or ChatGPT on the web, in the desktop app or in the phone app, and cannot run commands on the user's computer: follow B.
• Your app adds MCP servers as custom connectors with OAuth (for example Muse by Meta), and you cannot run commands on the user's computer: follow C.
• You can already use KUMODeck tools in this conversation: tell the user in one line that it is connected and skip to When it is connected.

Do not ask the user which one you are. Start right away.

A. An AI agent that can run commands#

1. Run npx kumodeck connect --api https://api.kumodeck.com in the user's project. It opens KUMODeck in the user's browser once: tell them to sign in and press Allow.
2. Tell the user: "In this conversation I'll use KUMODeck's commands. From the next conversation, KUMODeck's MCP tools work too." Keep going in this conversation with the KUMODeck CLI.
3. After you make or fix something, put it on the test app (development) and end with one line, not a question: "Test version: https://…. Say "publish it" when you want to publish." (testAppNote in npx kumodeck test-deploy --json has it in the user's language). When the user has seen it and says "publish it" (or the like) → production (npx kumodeck publish: the whole update, and they confirm it once in the browser). A publish request before they have seen it starts on the test app. Codex follows the Codex flow in the deploy Skill instead.
4. Never read saved KUMODeck tokens, config files or keys to call the KUMODeck API yourself, and do not search the web for how. If something is not available yet (the CLI says so), tell the user plainly and offer one thing you can do instead: a new conversation does not change it. Only if the CLI itself cannot run here (not installed, cannot sign in), ask the user to start a new conversation: MCP tools are loaded when a conversation starts.

If you cannot run that command: add the KUMODeck Preview (v0.2) MCP server https://mcp-staging.kumodeck.com/mcp to your MCP settings under the name kumodeck-preview (remote, Streamable HTTP, sign-in with OAuth). The line for each agent is in Use from an AI agent (MCP). Then tell the user what they still need to do, for example restart you, or sign in to KUMODeck in the browser and approve.

B. Claude or ChatGPT on the web or a phone#

You cannot run commands on the user's computer. Give the user the steps to add KUMODeck Preview (v0.2) as a custom connector. For most people this is the first time.

How to guide:

• Ask the user nothing; write the steps right away (you already know whether you are Claude or ChatGPT).
• Do not ask the user to install a browser extension or turn on computer control. The user does the settings.
• Give the whole checklist in one message. Do not stop after each click to ask what the user sees. The user comes back and says "done" after the checklist, or describes the problem.
• Write two short checklists. A) First time: open the settings → add a custom connector → paste the values below → sign in to KUMODeck → keep "Build and publish (recommended)" and press Connect (or Allow). B) Already added before: open KUMODeck Preview (v0.2) in the same settings and press Reconnect. Do not add a second one. Do not disconnect.
• If your own app shows a confirmation screen (such as allowing the connection or sharing chats and memory), write in A that the user presses its button. Add that your app stops there, not KUMODeck.
• Once, at the start, tell the user to keep this conversation open and open every link in a new tab (Cmd-click on a Mac, Ctrl-click on Windows).
• Give the direct link to a settings page only if you are sure it is the current correct URL, as a full clickable link starting with https://.
• When the user says "done", check with projects_list (read only). Do not say it works until projects_list succeeds. If the tools are not in this conversation, tell the user to start a new conversation, select KUMODeck Preview (v0.2) and try there.
• If "Authentication accepted. Please try again" appears twice, the user stops and tells you the exact message, the time (with time zone) and the step. Do not make them keep retrying.
• Do not mention plan limits, admins or developer mode unless the user's screen does not match.

Facts:

• Connection URL: https://mcp-staging.kumodeck.com/mcp
• KUMODeck account (sign in here if asked): https://dashboard.kumodeck.com
• Claude: Customize → Connectors → + Add → Add custom connector. Name: KUMODeck Preview (v0.2). Remote MCP server URL: the URL above → Add. Sign in on the KUMODeck page that opens and press Allow. In a conversation: + → Connectors → turn on KUMODeck Preview (v0.2).
• ChatGPT: Plugins → + → Add custom MCP server. Name: KUMODeck Preview (v0.2). Server URL: the URL above. Authentication: OAuth. Tick "I understand and want to continue" → Create as a plugin. Press + to install it, sign in on the KUMODeck page and press Allow. In a conversation: type @ and pick KUMODeck Preview (v0.2).
• Only if the user's screen does not match: Claude Free allows one custom connector (remove the other one). If ChatGPT has no such button, try Developer mode in Settings → Apps → Advanced settings. Work and school accounts need their admin. The phone apps cannot add it (add it in a computer browser; then it works on the phone too).

If you were connected before but now cannot use the KUMODeck tools in this conversation: tell the user to add KUMODeck Preview (v0.2) again from the + in the message box (in Claude: + → Connectors, and turn KUMODeck Preview (v0.2) on again), then ask again. Removing and adding the connector in settings is not needed.

C. Another AI app with custom connectors (OAuth)#

• Do not search for KUMODeck Preview (v0.2) in the app's list (Search plugins or directory). Add it as a custom connector with the connection URL below.
• If your own app shows a confirmation you are not allowed to press (in Muse: allowing a connection that shares related chats, and memory if it is on, with KUMODeck), the user presses it. Write it in the steps ("press [button] on that screen"), not as a question. Add that your app stops there, not KUMODeck.

Facts:

• Connection URL (put it in the connector's URL field): https://mcp-staging.kumodeck.com/mcp
• Name: KUMODeck Preview (v0.2)
• Client ID: in Muse, kumodeck-muse (registered for Muse in advance, no client secret, it returns only to Muse). If another app asks for a client ID, use the one you make under "Register yourself" below.
• Client secret: none (public client with PKCE)

Register yourself (when the app asks for a client ID and there is no fixed one; OAuth dynamic client registration, which you may do yourself):

1. Read https://mcp-staging.kumodeck.com/.well-known/oauth-protected-resource → read /.well-known/oauth-authorization-server on the server in authorization_servers → it lists authorization_endpoint, token_endpoint and registration_endpoint.
2. POST JSON to registration_endpoint: client_name (your app's name), redirect_uris (your app's OAuth callback, exactly the value it sends to /authorize), token_endpoint_auth_method: "none", grant_types: ["authorization_code", "refresh_token"], response_types: ["code"].
3. Put the returned client_id in the connector's client ID field (if you give it to the user, give only that, on one line). PKCE with S256 is required. A registration that is not used for 90 days is removed (then register again).

Steps for the user (all in one message; the user comes back and says "done" after them):

A) First time:

1. On the screen that adds a connector (in Muse: "Add custom connector"), put the connection URL above in the URL field and the client ID above in the client ID field, and press Add.
2. The KUMODeck page opens. The user signs in, keeps "Build and publish (recommended)" and presses Connect (Allow when adding permissions). That is the last button the user presses (plus your app's own confirmation, if it shows one).

B) Already added before: open KUMODeck Preview (v0.2) in the same settings and reconnect it. Do not add a second one. Do not disconnect.

Check that it is connected:

• When the user says "done", call projects_list once (it only reads the list of projects and changes nothing). If it answers, the connection is done. Do not say it works before that.
• If the KUMODeck tools do not appear in this conversation, or the app says there are no credentials yet: many apps load tools and credentials when a conversation starts. Tell the user in one line: "It is connected. Start a new conversation and ask there." Do not keep trying in the same conversation.
• If "Authentication accepted. Please try again" appears twice, the user stops and tells you the exact message, the time (with time zone) and the step.

Names (all the same connection):

When it is connected#