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 withki-*components) andkimen-genui(wire the generative UI layer). They tell the agent where Kimen’s contracts live and which mistakes to avoid. - Tools: the
kimen-mcpserver 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.
What works where
Section titled “What works where”| 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.
Step 1: give your agent the Kimen skills
Section titled “Step 1: give your agent the Kimen skills”The skills live in the repository under
plugins/kimen/skills.
They follow the Agent Skills format, so every
client below reads the same files.
Claude Code
Section titled “Claude Code”Install the plugin from the repository’s marketplace:
claude plugin marketplace add kimen-dev/kimenclaude plugin install kimen@kimenInside 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/kimencodex plugin add kimen@kimenCodex 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.
Antigravity
Section titled “Antigravity”From a clone of the repository:
agy plugin install ./kimen/plugins/kimenThe 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.
Gemini CLI
Section titled “Gemini CLI”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/kimenUse 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.
Other agents
Section titled “Other agents”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-genuiIt 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/skillscp -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.
No install at all: a note in AGENTS.md
Section titled “No install at all: a note in AGENTS.md”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`) anddesign 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.Step 2: connect kimen-mcp
Section titled “Step 2: connect kimen-mcp”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 Code
Section titled “Claude Code”--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.
Claude Desktop
Section titled “Claude Desktop”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", } }}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.
This writes to ~/.codex/config.toml, which the Codex CLI, the IDE
extension and the desktop app share:
[mcp_servers.kimen]command = "npx"Antigravity
Section titled “Antigravity”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", } }}OpenCode
Section titled “OpenCode”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", "enabled": true } }}opencode mcp list should report kimen as connected.
Cursor and VS Code
Section titled “Cursor and VS Code”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.
Other clients
Section titled “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 |
Optional: lock the server down
Section titled “Optional: lock the server down”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:
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.
Alternative: run kimen-mcp from a clone
Section titled “Alternative: run kimen-mcp from a clone”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.gitcd kimenpnpm install --frozen-lockfilepnpm exec nx run @kimen/mcp-server:buildexport 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.
Step 3: check it works
Section titled “Step 3: check it works”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.0and send payloads asapplication/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.
Troubleshooting
Section titled “Troubleshooting”- 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 afterkimen-mcpor the path. If the command works in your terminal but not in a desktop app (Claude Desktop, Antigravity), the app is not findingnpxornode: see thePATHnote 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-componentorunknown-prop. The model guessed a name. It should callkimen_describe_componentfirst; props use the attribute names (line-numbers, notlineNumbers).url-schemeor a refused URL.kimen-mcpsurfaces cannot load URLs. Render images and links from your own page or server instead.