---
title: "Kition SDK for AI agents — MCP tools for Claude Code, Cursor, Codex and any MCP client"
description: "One stdio MCP server, kition-kits-mcp, lets Claude Code, Claude Desktop, Cursor, Codex or any MCP client inspect files, run real commands, check its own output and work in drafts a person merges. Free, no key."
canonical: "https://developer.kition.ai/agents"
---

> Canonical HTML: [https://developer.kition.ai/agents](https://developer.kition.ai/agents)

Agents · kition-kits-mcp

# Real tools for your agents

Every kit is an MCP server with basic KHP support. Register one stdio server with your client and your agent inspects files, runs the kit’s own commands, checks its output and leaves drafts for a person to merge.

-   **1**server for every kit
-   **10**tools per kit, or 10 in all with `--unified`
-   **0**keys: free on any machine

Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. Works with React, Vue, Svelte, plain JS, Node, Next.js and any MCP client.

For AI agents reading this page

-   [agents.md](https://developer.kition.ai/agents.md)
-   [llms.txt](https://developer.kition.ai/llms.txt "Index of every page, with its Markdown twin")
-   [llms-full.txt](https://developer.kition.ai/llms-full.txt "The docs and the way-in pages in one file")
-   [commands.jsonl](https://developer.kition.ai/commands.jsonl "The agent commands of the published kits, one JSON object per line")
-   [SKILL.md](https://developer.kition.ai/skill/SKILL.md "The agent skill: how to use the kit tools")

Connect your agentstdio · npx

1.  **Get the server**npx downloads it
    
    terminal
    
    ```
    # Node.js 20+; macOS, Linux (glibc) and Windows x64
    npx -y @kition/kits-mcp --help
    # or install the command kition-kits-mcp once
    npm install -g @kition/kits-mcp
    ```
    
    The package brings the server and the published kits (Note and Table) for your platform. Your client starts it; you do not run it yourself.
    
2.  **Register it with your client**one server, every kit
    
    terminal · in your project folder
    
    ```
    claude mcp add kition -- npx -y @kition/kits-mcp --workspace "$PWD"
    ```
    
    Run it in the project folder: the shell fills in its absolute path. Add --scope project to share it through the project’s .mcp.json, and /mcp shows whether the server started.
    
    With the server installed instead
    
    terminal · in your project folder
    
    ```
    claude mcp add kition -- kition-kits-mcp --workspace "$PWD" --kits-dir <kits-folder>
    ```
    
    claude\_desktop\_config.json · .mcp.json
    
    ```
    {
      "mcpServers": {
        "kition": {
          "command": "npx",
          "args": ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"]
        }
      }
    }
    ```
    
    Any client with an mcpServers file. Use absolute paths: Claude Desktop does not start servers in your project folder.
    
    With the server installed instead
    
    claude\_desktop\_config.json · .mcp.json
    
    ```
    {
      "mcpServers": {
        "kition": {
          "command": "kition-kits-mcp",
          "args": ["--workspace", "/absolute/path/to/folder", "--kits-dir", "/absolute/path/to/kits"]
        }
      }
    }
    ```
    
    .cursor/mcp.json
    
    ```
    {
      "mcpServers": {
        "kition": {
          "command": "npx",
          "args": ["-y", "@kition/kits-mcp", "--workspace", "${workspaceFolder}"]
        }
      }
    }
    ```
    
    In the project’s .cursor/mcp.json (or ~/.cursor/mcp.json for every project). Cursor fills in ${workspaceFolder}, the folder that holds .cursor/.
    
    With the server installed instead
    
    .cursor/mcp.json
    
    ```
    {
      "mcpServers": {
        "kition": {
          "command": "kition-kits-mcp",
          "args": ["--workspace", "${workspaceFolder}", "--kits-dir", "/absolute/path/to/kits"]
        }
      }
    }
    ```
    
    ~/.codex/config.toml
    
    ```
    [mcp_servers.kition]
    command = "npx"
    args = ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"]
    ```
    
    Codex does not start servers in your project folder: give the folder’s absolute path.
    
    With the server installed instead
    
    ~/.codex/config.toml
    
    ```
    [mcp_servers.kition]
    command = "kition-kits-mcp"
    args = ["--workspace", "/absolute/path/to/folder", "--kits-dir", "/absolute/path/to/kits"]
    ```
    
    any MCP client · stdio
    
    ```
    transport  stdio
    command    npx
    args       -y @kition/kits-mcp --workspace /absolute/path/to/folder
    # options  --unified · --drafts · --sandbox
    ```
    
    A stdio server: register the command and its arguments. --workspace is the only folder it reads or writes.
    
    With the server installed instead
    
    any MCP client · stdio
    
    ```
    transport  stdio
    command    kition-kits-mcp
    args       --workspace /absolute/path/to/folder --kits-dir /absolute/path/to/kits
    # options  --unified · --drafts · --sandbox
    ```
    

## Or let your agent do it

01

**Paste this into your agent**

One prompt for Claude Code, Cursor or Codex: it says where the server comes from, how to register it on this project, the loop to follow, and where the machine-readable docs are.

prompt · any coding agent

Set up the Kition SDK kit tools (an MCP server) for this project, then use them for the files they cover.

1. Read https://developer.kition.ai/agents.md (setup for each client) and https://developer.kition.ai/skill/SKILL.md (how to use the tools).
2. Get the server with \`npx -y @kition/kits-mcp\` (Node.js 20 or later); it brings the published kits.
3. Register it as a stdio MCP server named "kition" in this client, with --workspace set to this project's absolute path. Show me the config change before you write it, and ask before you edit a file outside this project.
4. Check that it starts and lists its tools (note\_\* per kit, or kit\_\* with --unified).
5. When you edit a file with it: \_inspect it first, find real command ids with \_commands, change it with \_run, then call \_check and fix what it reports. With drafts on, finish with \_draft\_ready and never merge: I review and merge.

Only the Note kit (Markdown) is published; the other kits are not yet.
Machine-readable docs: https://developer.kition.ai/llms.txt (index), https://developer.kition.ai/llms-full.txt (the docs and way-in pages in one file), https://developer.kition.ai/commands.jsonl (the published kits' agent commands), https://developer.kition.ai/skill/SKILL.md (agent skill).

**Claude Code plugin and agent skill**

The plugin starts the same server on your project folder with one tool set for all kits, adds the Note kit’s editing skill, and gives you draft review commands: `/kition-kits:drafts-list`, `drafts-compare`, `drafts-merge`, `drafts-discard`. Only you start a merge or a discard.

terminal · kition-sdk checkout

```
# from a kition-sdk checkout
claude plugin marketplace add ./plugins/claude-code
claude plugin install kition-kits@kition
```

Any other coding agent: give it [the agent skill, SKILL.md](https://developer.kition.ai/skill/SKILL.md). It tells the agent how to use the tools; the full setup is in the [agent guide](https://developer.kition.ai/docs/agent#connect-your-agent).

## How it works

02

1.  Your agent**Any MCP client**
    
    Claude Code, Cursor, Codex or your own agent starts kition-kits-mcp as a stdio server on one workspace folder.
    
2.  kition-kits-mcp**One workspace, every kit**
    
    It launches each kit’s headless executable and offers its tools. No Kition app runs; paths outside the workspace are refused.
    
3.  A person**Reviews the draft**
    
    With drafts on, the file stays as it is until a person compares the draft and merges it. The agent never merges.
    

## The tools

03

-   [`<prefix>_inspect`](https://developer.kition.ai/docs/agent)The document as JSON; preview: true adds a rendered preview.
-   [`<prefix>_commands`](https://developer.kition.ai/docs/agent)Search the kit’s commands by keywords. Use the ids it returns, never guessed ones.
-   [`<prefix>_run`](https://developer.kition.ai/docs/agent)Run command steps in order, then save: { path, steps: \[{ command, params }\] }.
-   [`<prefix>_query · <prefix>_batch`](https://developer.kition.ai/docs/agent)Read and edit objects through the object model, for many small changes.
-   [`<prefix>_check`](https://developer.kition.ai/docs/agent)What the kit finds wrong with the file: { diagnostics: \[{ code, severity, target, message, fix? }\] }.
-   [`<prefix>_create · <prefix>_export`](https://developer.kition.ai/docs/agent)A new file, or the file in another format.
-   [`<prefix>_draft_ready · <prefix>_draft_reopen`](https://developer.kition.ai/docs/agent#drafts)Ask for review of the agent’s draft, or reopen it. Merge and discard are not tools.

Failed calls answer `isError` with `structuredContent.error.code` (`not-found`, `read-only`, `unknown-command`, `invalid-params`, `conflict`, …). `kition-kits-mcp --schemas` prints every tool’s argument and result JSON Schema.

Default · per kit

**`note_*`, `sheet_*`, …**

Each kit adds its own ten tools, named by its prefix, so the tool name says which kit it is for. Choose it with one or two kits installed.

tools/list

```
$ kition-kits-mcp --workspace . --kits-dir kits
# tools/list: ten per kit, named by its prefix
note_inspect       note_commands
note_run           note_check
note_query         note_batch
note_export        note_create
note_draft_ready   note_draft_reopen
# + sheet_*, slide_*, doc_* … for each kit installed
```

\--unified · one set

**`kit_*`, routed by extension**

Ten tools for every kit; each call goes to the kit for its file’s extension. Choose it with several kits, or when your client limits tools or tool-definition tokens. The Claude Code plugin uses it.

tools/list

```
$ kition-kits-mcp --workspace . --kits-dir kits --unified
# tools/list: ten, however many kits
kit_inspect        kit_commands
kit_run            kit_check
kit_query          kit_batch
kit_export         kit_create
kit_draft_ready    kit_draft_reopen
# notes/plan.md → note · deck.pptx → slide
```

With Note alone, both give ten tools.

**The loop: inspect, run, check**

Tell your agent to call `_check` after every edit and fix what it reports, errors first, matching on `code` rather than the message. The kit checks its own file, so the agent sees what it broke before a person does.

SKILL.md · the loop

```
_inspect  { path }                 # look first
_commands { path, query }          # real command ids, never guessed
_run      { path, steps: [...] }   # edit, then save
_check    { path }                 # fix each error, then warning
          ↻ until _check is clean
_draft_ready { path }              # with drafts: hand it to the person
```

**Drafts: a person merges**

Start the server with `--drafts` (or pass `draft: true`) and the agent’s edits go to a draft in the workspace’s `.kition/drafts/`; the file stays as it is. The agent hands it over with `_draft_ready`. You compare and merge, on the command line or from your server.

the person’s side · terminal

```
kition-kits-mcp drafts list --workspace .
kition-kits-mcp drafts compare notes/plan.md --previews \
  --workspace . --kits-dir <kits-folder>
# refused as stale if the file changed since the draft forked
kition-kits-mcp drafts merge notes/plan.md --workspace . --kits-dir <kits-folder>
kition-kits-mcp drafts discard notes/plan.md --workspace . --kits-dir <kits-folder>
```

## KHP tiers

04

Kit Harness Protocol (KHP) is the open standard behind the tools. A kit conforms at a tier, and `khp check` tests it; each tier includes the one before.

KHP tiers, and the kits at each today (16 kits)

| Tier | A kit at this tier has | Kits today |
| --- | --- | --- |
| Basic `basic` | \_inspect, \_commands, \_run and \_check; a schema for every agent-facing command; stable errors; atomic runs; the draft tools when the kit declares drafts. | The other 15 kits |
| Agent-ready `agent-ready` | Basic, plus works without its editor, full schema coverage, no network, a real check with its catalogue, a real preview, create and export, determinism. | Design |
| Agent-ready complete `agent-ready-complete` | Agent-ready, plus a kit guide for agents, edits that address only what they change by id, name or path, and running under a sandbox. | None yet |

Read the standard at [kitharness.org](https://kitharness.org/).

## The bench

05

Multi-turn edits are where agents break files: a later turn revisits an earlier slide and damages content it was not asked to touch. Multi-turn slide edits: 30/30 clean with KHP vs 18/30 with flat MCP tools (p = 0.0001).

What it does not show: that KHP makes a single simple edit more likely to succeed, or that it is the cheapest interface for every task.

**Multi-turn slide edits, 30 runs each**Each run revisits earlier slides. p = 0.0001.

-   KHP tools
-   Flat MCP tools

**Runs that finished clean**

KHP tools

30 of 30

Flat MCP tools

18 of 30

**Runs that damaged other content**

KHP tools

0 of 30

Flat MCP tools

12 of 30

Show as a table

| Runs out of 30 | KHP tools | Flat MCP tools |
| --- | --- | --- |
| Runs that finished clean | 30 | 18 |
| Runs that damaged other content | 0 | 12 |

Pilot results from khp-bench, run by KHP’s maintainer: [method, limits and how to reproduce](https://kitharness.org/benchmark/).

## A complete example

06

An agent adds a section with a task to a note in a workspace folder over MCP, then asks the kit to check the file.

kition-sdk · examples/agent-mcp/run.mjs

run.mjs

```
const server = await connect(mcp, ['--workspace', workspace, '--kit', note])

// The note: one more section, with a task under it.
const before = inspected(await call('note_inspect', { path: file, preview: false })).details.headings
await call('note_run', {
  path: file,
  steps: [{
    command: 'block.append',
    params: { markdown: `## Agent review ${before + 1}\n\n- [ ] Check the numbers` },
  }],
})
const after = inspected(await call('note_inspect', { path: file, preview: false })).details

// Verify: the kit checks its own file.
const answer = await server.call('note_check', { path: file })
const diagnostics = answer.structuredContent?.diagnostics ?? []
const errors = diagnostics.filter((item) => item.severity === 'error')
```

**The person merges, from your server**

Your page’s server lists the drafts, compares one with previews, and merges it when the person approves. In an open editor, the same review happens in the page: [Embed](https://developer.kition.ai/embed).

Agents that work in Git worktrees can use the command line instead: [kiv, Git for kit files](https://developer.kition.ai/kiv) diffs and merges slide files and lands parallel branches.

docs/sdk/agent.md

```
import { workspaceDrafts } from '@kition/script/node'

// the SDK bundle's server and kits
const drafts = workspaceDrafts({
  server: 'bin/<platform>/kition-kits-mcp', workspace, kitsDir: 'kits',
})
// { path, state: 'ready', stale, mode, … }
const [draft] = await drafts.list()
// { diff, summary, previews }
const comparison = await drafts.compare(draft.path, { previews: true })
// the person approved: the draft becomes the file
await drafts.merge(draft.path)
```

## Limits and requirements

07

-   The installed server finds the kits from `--kits-dir` (one folder per kit, its `kit.json` and executable), `--kit <path>`, `KITION_KIT_<KIT>_BINARY`, or the `PATH`; `--list-kits` says what it found.
-   `--workspace` is the only folder it reads or writes; every tool names its file by `path` relative to it, and paths outside it are refused.
-   `--sandbox` runs every kit process in the operating system’s sandbox (macOS, Linux); off by default.

-   Without `--unified`, each kit whose executable is set adds its own tools, prefixed with the kit’s name (`note`, `sheet`, `slide`, `doc`, …).
-   In an open editor, `editor.agentPort()` serves the same tools on the live document, relayed by your page and server.
-   The Claude Code plugin’s launcher is a POSIX shell script (macOS and Linux); on Windows, register the server yourself.

[Run the kits from code instead](https://developer.kition.ai/headless)

## Give your agent real tools

`npm i @kition/script`

[Open playground](https://developer.kition.ai/playground)
