Kyoso MCP server

Connect Kyoso to Claude, Codex, or any MCP-compatible AI app and run creative production from your own environment.

The Kyoso MCP server is a new integration. The tool surface is still growing, and feedback on what's missing is welcome.

Kyoso's Model Context Protocol (MCP) server lets you run creative production directly from compatible AI apps such as Claude Desktop, Claude Code, and Codex. Think of it as an authenticated API that an AI agent can use on your behalf: it signs in as you, works in your projects, and drives the same Kyoso agent you'd talk to in the app.

With it connected, your agent can:

Create a project and work on its canvas — spin up a new project, then generate and edit images, generate video, adapt aspect ratios, and lay out frames and compositions.
Pass context in from wherever it lives — send a brief, a spec, or local files (product shots, logos, references) straight from your machine into a project as assets the agent can use.
Read the canvas back — list the node tree, inspect a node's properties, and download a rendered PNG of any node or frame.
Stay on-brand — work is scoped to one of your brands, so the agent applies the same brand knowledge it uses in the app.

Everything runs against your real account: your brands, your projects, your credits. You can open the canvas in your browser and watch the work land live while the agent runs.

Connect

MCP URL: https://mcp.kyoso.com/mcp

Authentication is OAuth against your Kyoso (Lumina) account — you'll be sent to a browser to sign in and approve access the first time your client connects. There's nothing to copy, no API key to manage.

If authentication fails, go to app.kyoso.com and sign in if you aren't already. That refreshes your session and lets the MCP authentication proceed. Then retry from your client.

Pick the setup that matches your client.

Ask your agent to do it

If your AI app can manage its own MCP connections, just tell it:

Add the Kyoso MCP, user scope, name it `kyoso`. The URL is https://mcp.kyoso.com/mcp.
If sandboxing will prevent writes to the configuration file, run with no sandboxing.
Verify the configuration to ensure the installation succeeded. If authentication
fails, remind me to first login at https://app.kyoso.com/, then authenticate.

This works in Claude Code, Codex, and other agents that can edit their own MCP configuration — but not in Claude Desktop, which can't add its own connectors. Use the Claude Desktop steps below instead.

Claude Code

claude mcp add --transport http kyoso https://mcp.kyoso.com/mcp

Codex

codex mcp add kyoso --url https://mcp.kyoso.com/mcp

Claude Desktop

Open Settings → Connectors → Add custom connector, name it kyoso, paste the URL above, and sign in when the browser opens.

To check the connection worked, ask your agent to run the whoami tool — it returns your Kyoso user id and confirms auth is good.

How working through the MCP feels

You don't drive Kyoso tool-by-tool. Your agent describes what it wants in plain language and Kyoso's agent does the work:

Your agent creates or picks a project and hands you back a canvas URL — open it to follow along.
It starts a step: a single natural-language prompt like "Make three vertical variants of the selected product shot and a 5-second hook video." Kyoso breaks that into sub-steps itself.
The step runs in the background. Your agent can wait and report when it's done, or hand you the step id and move on — the work continues either way, and you can watch it finish on the canvas.
When it's done, your agent reads back what happened, and can render any node to see the result.

If Kyoso needs a decision before it can continue, it asks — the question comes back in the step's messages, and your agent answers by starting another step with your answer.

Attaching local files

Local files become project assets before the agent can use them. Your agent handles this in three calls (prepare an upload, send the bytes, finalize), then passes the asset ids into the next step. Processing — thumbnails, descriptions — happens in the background, and the step waits for it, so there's no need to poll.

Assets attached this way behave like anything you'd upload in the app. See Working with files and Supported file types.

Tool surface

Tool	What it does
`whoami`	Confirms auth and returns your user id.
`kyoso_create_project`	Creates a project (in a brand) and returns its id and canvas URL.
`kyoso_start_step`	Runs a natural-language instruction on a project, optionally against a selection and attached assets.
`kyoso_step_execution_status`	Waits for a running step and reports whether it's finished.
`kyoso_step_messages`	Reads back everything the agent said and did during a step, including questions.
`kyoso_list_canvas_tree`	Lists the canvas node hierarchy — ids, types, names, sizes.
`kyoso_inspect_node`	Returns a node's detailed properties, and its subtree.
`kyoso_render_node`	Renders a node as an image straight into the conversation.
`kyoso_get_render_url`	Renders a node and returns a link to download the PNG.
`kyoso_prepare_project_asset_upload`	Starts uploading a local file as a project asset.
`kyoso_finalize_project_asset`	Completes an upload and starts processing.
`kyoso_project_asset_status`	Checks an asset's processing status.

For the tools available inside the app, see the Tools reference.

Troubleshooting

You get an auth error when connecting or calling a tool. Your Kyoso session is stale. Sign in at app.kyoso.com to refresh it, then retry from your client. If it persists, remove and re-add the MCP server so it runs a fresh OAuth flow.

A step comes back "busy." Only one step runs at a time per project. Wait for the current one to finish, or work in a second project.

Good to know

One conversation per project. A project has a single agent conversation, so successive steps continue the same thread — which is how follow-ups and answers to questions land in the right context.
Steps are asynchronous. They keep running whether or not your client stays attached. Closing your terminal doesn't cancel the work.
Credits apply. Generations started through the MCP draw on the same credits as work in the app — see Credit usage.
Access follows your account. The agent can only reach the brands and projects you can, and every call is authorized as you.
Render links expire. A download URL from kyoso_get_render_url stops working a week after it was created, and always serves the render as it was at that moment — fetch a new one after edits.

Kyoso MCP server

On this page