MCP tools

Start the server with kol mcp (or kol-mcp). It speaks MCP over stdio. Every tool returns one JSON text block like the CLI's --json output; on failure isError is true and the JSON has error and hint.

Every tool also takes host (the Kol host URL). Tools that work on a project take dir (default: the folder the agent started the server in).

kol_whoami

Who is signed in to the Kol host, and whether they have an AI key (needed for try-outs and tests).

No arguments.

kol_login_start

Start signing in. Returns a code: show it to the user and ask them to approve it in the Kol app (Companions → Creator portal → enter the code). Then call kol_login_finish with code and deviceCode.

No arguments.

kol_login_finish

Wait until the user approved the code in the Kol app, then keep the sign-in on this computer.

Argument	Type	Description
code (required)	string
deviceCode (required)	string
timeoutSec	number	Default 120.

kol_init

Make a new Kol AI project folder: kol.json, persona.md (template to rewrite), knowledge/, tests/, AGENTS.md. Read AGENTS.md next.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
name	string
kind	companion | service	companion (default): people get their own copy. service: a public AI anyone can call, with its own Kol ID.

kol_schema

Allowed icons, colors, voices, prices and length limits for kol.json.

No arguments.

kol_validate

Check the project: every problem by field. Fix them before trying or pushing.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.

kol_prompt

The exact instructions, greeting and tools the AI gets in a call (persona + knowledge + platform rules). Free: no AI call.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
as	owner | standIn	standIn: as if it answers a call for its owner (companions that allow it).

kol_try

Talk to the project's draft in text (nothing is saved, tools don't deliver). No message: its greeting. Use session to continue a conversation, reset to start over. Uses the user's AI key.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
as	owner | standIn	standIn: as if it answers a call for its owner (companions that allow it).
message	string
session	string
reset	boolean

kol_test

Run the scripted conversations in tests/*.json against the draft. Returns each reply and what failed. Uses the user's AI key.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
only	string	Run only the test with this name or file.

kol_push

Save the project on the host as a draft (only its creator sees it; they can talk to it by voice in the app) and sync its knowledge. Refuses to change a published AI unless live is true.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
live	boolean

kol_publish

Push, then put the AI in the Kol marketplace where anyone can find it. Only when the user asked to publish. off: take it out of the marketplace.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
off	boolean

kol_list

The user's AIs on the host, with installs, calls, minutes and requests.

No arguments.

kol_status

One AI: published or not, version, numbers, knowledge, and whether this folder has changes not pushed yet.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
id	string	A creation id (see kol_list). Default: the one this project is linked to.

kol_requests

Requests (orders, bookings) the AI took from callers.

Argument	Type	Description
dir	string	The project folder (has kol.json). Default: the current folder.
id	string	A creation id (see kol_list). Default: the one this project is linked to.