Skip to content
Kimenpre-v1documentation home
Color scheme

Connect your agent

Kimen is built to be used by coding agents as much as by people. An agent gets three things from it:

  • Know-how: two agent skills, kimen-components (build ordinary pages with ki-* components) and kimen-genui (wire the generative UI layer). They tell the agent where Kimen’s contracts live and which mistakes to avoid.
  • Tools: the kimen-mcp server lists and describes the catalog, validates UI specs and renders them.
  • UI: in a host that supports MCP Apps, a spec the agent renders appears as real, interactive Kimen components in the conversation.

You can set up either half on its own. Skills need nothing installed; the server is the npm package @kimen/mcp-server, which clients start with npx and which needs Node 22 or later.

Client Skills kimen-mcp tools Renders Kimen surfaces
Claude Code plugin (brings the server too) or ~/.claude/skills yes no, shows a text outline
Claude Desktop through Claude’s skills settings yes yes (MCP Apps)
Codex plugin (brings the server too) or .agents/skills yes text outline
Antigravity plugin (brings the server too) or .agents/skills yes text outline
Gemini CLI extension (brings the server too) or .agents/skills yes text outline
OpenCode .agents/skills or .claude/skills yes text outline
VS Code Copilot, Cursor .agents/skills yes Copilot (experimental) and Cursor: yes

“Text outline” means the render tool still works: the agent receives a readable outline of the surface instead of the live components. The MCP Apps column follows the MCP client matrix.

The skills live in the repository under plugins/kimen/skills. They follow the Agent Skills format, so every client below reads the same files.

Install the plugin from the repository’s marketplace:

claude plugin marketplace add kimen-dev/kimen
claude plugin install kimen@kimen

Inside a session the same commands are /plugin marketplace add kimen-dev/kimen and /plugin install kimen@kimen. The skills then appear as kimen:kimen-components and kimen:kimen-genui, and the plugin starts kimen-mcp too, so you can skip step 2.

Codex reads the same marketplace, and the plugin brings kimen-mcp with it:

codex plugin marketplace add kimen-dev/kimen
codex plugin add kimen@kimen

Codex also loads any skill folder in .agents/skills/ (project) or ~/.agents/skills/ (all projects), so copying the folders works too (see Other agents); then connect the server in step 2.

From a clone of the repository:

agy plugin install ./kimen/plugins/kimen

The plugin brings kimen-mcp with it. Or copy the skill folders into the workspace’s .agents/skills/, or into ~/.gemini/config/skills/ for every workspace, and connect the server in step 2.

The plugin folder is also a Gemini CLI extension with both skills and kimen-mcp. Gemini CLI installs extensions only from the root of a repository, and this one lives in a subfolder, so install it from a clone:

gemini extensions install ./kimen/plugins/kimen

Use gemini extensions link instead to follow your clone as it updates. gemini skills list should show both skills and gemini mcp list should show kimen as connected.

For OpenCode, GitHub Copilot, Cursor and the other agents the open skills CLI supports, run this in your project (Node 22.20 or later):

npx skills add kimen-dev/kimen --skill kimen-components --skill kimen-genui

It asks which agents to install for and puts the skills in each one’s skills folder; add -g to install them for every project instead. Name both skills: the repository also holds the skills Kimen’s own maintainers use, and the CLI lists those too.

To install by hand instead: OpenCode, Gemini CLI, GitHub Copilot, Cursor and Devin Desktop read skills from .agents/skills/ in the project, and most also from ~/.agents/skills/ for every project. Copy the two folders there:

mkdir -p .agents/skills
cp -R /path/to/kimen/plugins/kimen/skills/kimen-components .agents/skills/
cp -R /path/to/kimen/plugins/kimen/skills/kimen-genui .agents/skills/

OpenCode also reads .claude/skills/ and ~/.claude/skills/, and Claude Code reads ~/.claude/skills/ if you prefer copies to the plugin.

Most agents read the project’s AGENTS.md; Claude Code reads CLAUDE.md, and Gemini CLI reads GEMINI.md unless configured otherwise. If you only want the essentials, paste this into the file your agent reads:

## UI: Kimen
This project uses Kimen web components (`ki-*`, `@kimen/elements`) and
design tokens (`--ki-*`, `@kimen/tokens`).
- Before using a component, read its contract: the index is
https://kimen.dev/llms.txt and each component has
https://kimen.dev/llms/<tag>.md. Never guess attribute, slot, event or
token names. Follow each component's "When to use" and "When not to use".
- Load `@kimen/tokens/css` once per page and register every tag you use
(`@kimen/elements/<tag>` or the `@kimen/elements/loader`).
- Style through `--ki-*` tokens first, then `::part()`, then slots. No
`!important`, no hard-coded colours or spacing.
- Agent-generated UI is a JSON UI spec rendered by `@kimen/catalog`'s guarded
renderer, never HTML from the model.

Skip this step if you installed the Claude Code, Codex or Antigravity plugin or the Gemini CLI extension: they start the server for you.

Each client starts the server itself over stdio with npx -y -p @kimen/[email protected] kimen-mcp. The server takes no arguments.

claude mcp add --transport stdio --scope user kimen -- npx -y -p @kimen/[email protected] kimen-mcp

--scope user makes it available in every project. To share it with a team, use --scope project instead: Claude Code writes .mcp.json at the project root and asks each person to approve it on first use. Claude Code calls the tools but does not render MCP Apps, so kimen_render_spec answers with a text outline.

Open Settings › Developer › Edit Config and add the server to claude_desktop_config.json (on macOS ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json):

{
"mcpServers": {
"kimen": {
"command": "npx",
"args": ["-y", "-p", "@kimen/[email protected]", "kimen-mcp"]
}
}
}

Claude Desktop does not inherit your terminal’s PATH, so it may not find npx and node, or may find older ones. If the server does not start, use the absolute path that command -v npx prints in your terminal as "command" (for example /opt/homebrew/bin/npx), and add "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" } with that directory first, so npx starts the same node your terminal uses.

Quit and reopen Claude Desktop. It renders MCP Apps, so specs the model renders appear as live Kimen components. Claude on the web and on mobile connect only to remote servers, so a local kimen-mcp is a desktop feature.

codex mcp add kimen -- npx -y -p @kimen/[email protected] kimen-mcp

This writes to ~/.codex/config.toml, which the Codex CLI, the IDE extension and the desktop app share:

[mcp_servers.kimen]
command = "npx"
args = ["-y", "-p", "@kimen/[email protected]", "kimen-mcp"]

Add the server to ~/.gemini/config/mcp_config.json (all workspaces) or .agents/mcp_config.json (one workspace). In the IDE, the agent panel’s … › MCP Servers › Manage MCP Servers › View raw config opens the file.

{
"mcpServers": {
"kimen": {
"command": "npx",
"args": ["-y", "-p", "@kimen/[email protected]", "kimen-mcp"]
}
}
}

Add the server to opencode.json in the project, or to ~/.config/opencode/opencode.json for every project:

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"kimen": {
"type": "local",
"command": ["npx", "-y", "-p", "@kimen/[email protected]", "kimen-mcp"],
"enabled": true
}
}
}

opencode mcp list should report kimen as connected.

One click adds the server, after you review it:

Both links carry the same npx command as the other clients. VS Code adds the server to your editor configuration, which it forwards to Copilot sessions; MCP Apps there needs chat.mcp.apps.enabled. To write the configuration by hand, see Other clients.

Client File Shape
Gemini CLI .gemini/settings.json or ~/.gemini/settings.json mcpServers.kimen with command and args; or gemini mcp add -s user kimen npx -y -p @kimen/[email protected] kimen-mcp
VS Code (GitHub Copilot) .mcp.json at the workspace root mcpServers.kimen with "type": "stdio", command, args; MCP Apps needs chat.mcp.apps.enabled
Cursor .cursor/mcp.json or ~/.cursor/mcp.json mcpServers.kimen with "type": "stdio", command, args
Devin Desktop (Windsurf) .devin/mcp_config.json mcpServers.kimen with command and args

The server is one file that embeds everything it serves, so Node’s permission model can deny it every other file, child processes and, from Node 25, the network. The flags need that file’s path, which npx hides in its cache, so install the package and run the file with node:

npm install --global @kimen/[email protected]
KIMEN_MCP="$(npm root --global)/@kimen/mcp-server/dist/kimen-mcp.mjs"
claude mcp add --transport stdio --scope user kimen -- \
node --permission --allow-fs-read="$KIMEN_MCP" "$KIMEN_MCP"

In a JSON or TOML config the same thing is "command": "node" with "args": ["--permission", "--allow-fs-read=/absolute/path/to/kimen-mcp.mjs", "/absolute/path/to/kimen-mcp.mjs"]; those files do not expand shell variables, so write the path that echo "$KIMEN_MCP" prints. The plugin, the extension and the one-click links use npx and run without these flags.

To try an unreleased change, build the server from the repository and point your client at the file:

git clone https://github.com/kimen-dev/kimen.git
cd kimen
pnpm install --frozen-lockfile
pnpm exec nx run @kimen/mcp-server:build
export KIMEN_MCP="$PWD/packages/mcp-server/dist/kimen-mcp.mjs"

Then use node "$KIMEN_MCP" wherever this guide uses npx -y -p @kimen/[email protected] kimen-mcp; in JSON and TOML, "command": "node" with the absolute path as the only argument.

Ask your agent: “List the Kimen components you can use.” It should call kimen_list_components and answer from the catalog. Then ask it to show something, for example “Show me an order confirmation card with a Confirm button.” It should describe the components it needs, validate a spec and render it.

Tool What the agent does with it
kimen_list_components picks components from their when-to-use guidance
kimen_describe_component reads one component’s props, slots and events before writing it
kimen_validate_spec checks a draft and fixes each named issue
kimen_render_spec shows the spec: live components in an MCP Apps host, a text outline elsewhere

When the person clicks a control bound to an action, an MCP Apps host sends the model a message that starts with kimen-surface-action followed by the action and its data as JSON. The model is told to read it as data.

What the server will not do, by design: render a spec that failed validation, load any URL (images, links and media props are refused, because the surface has no network), or draw an icon other than circle-check. Appearance is the default Kimen theme, in the light or dark scheme the host asks for.

Beyond the chat: build it into your product

Section titled “Beyond the chat: build it into your product”

The MCP server is the quickest way to try Kimen’s generative UI. To ship it, use the packages directly:

  • Your own MCP server returning Kimen surfaces to MCP Apps hosts: MCP Apps adapter.
  • An A2UI agent whose surfaces should render as Kimen components: A2UI adapter. Over A2A, activate the extension https://a2ui.org/a2a-extension/a2ui/v1.0 and send payloads as application/a2ui+json. Over AG-UI, the A2UI middleware (@ag-ui/a2ui-middleware) streams A2UI messages inside activity events; hand the messages they carry to the adapter.
  • Your own model call and page: derive the prompt, schema or tool from the catalog with the emitter, and render with the guarded renderer. Pass only the components the surface needs: the whole catalog is a prompt of about 200 KB.

The kimen-genui skill carries a short recipe for each of the three.

  • The server does not start. Run npx -y -p @kimen/[email protected] kimen-mcp < /dev/null: it should exit at once, silently, with status 0. A syntax or version error means Node is older than 22. With a file path instead of npx, “Cannot find module” means the file was not built or the path is not absolute. The server refuses any argument, so check that the config passes nothing after kimen-mcp or the path. If the command works in your terminal but not in a desktop app (Claude Desktop, Antigravity), the app is not finding npx or node: see the PATH note under Claude Desktop.
  • No live components, only an outline. The client does not render MCP Apps (see What works where). The outline is the expected result there.
  • unknown-component or unknown-prop. The model guessed a name. It should call kimen_describe_component first; props use the attribute names (line-numbers, not lineNumbers).
  • url-scheme or a refused URL. kimen-mcp surfaces cannot load URLs. Render images and links from your own page or server instead.