Reference

MCP tools

Every tool an agent sees, with its parameters and what it returns.

SoonThese pages describe Chronos Cloud, which opens from the waitlist. Running Chronos yourself? Self-host docs

Protocol

Transport: MCP streamable HTTP (protocol 2025-06-18, also 2025-03-26 and 2024-11-05). POST one JSON-RPC message, get one JSON answer; initialize opens a session (Mcp-Session-Id).
Auth: OAuth 2.1 with dynamic client registration and PKCE, or Authorization: Bearer ck_… (an API key). See Coding agents.
Results are text: SQL results as a psql-style table, others as one or more lines. Failures are normal results with isError: true and a message saying how to fix the call.
Branch: every tool that reads or writes rows takes branch (default main). Agents are taught to fork, write the world, and merge. In production they can’t write main at all; an agent with a merge policy changes main only by merging.
Which tools are listed follows what the agent may do: in production, merge lands nothing in main on its own.

Project tools

setup_project

Creates or finds the project’s database and makes it the session’s project. Returns DATABASE_URL and the files to write (.chronos/project.json, the .env line, .mcp.json, the CLAUDE.md block). Safe to call again: the same git remote, else name, gives the same project.

Parameter	Type	Required	Notes
`name`	string	yes	the project folder’s name
`git_remote`	string	no	`git remote get-url origin`

use_project

Makes an existing project the session’s project.

Parameter	Type	Required	Notes
`project_id`	string	yes	`prj_…`, from `.chronos/project.json`

usage

The project database’s size, open worlds, data out and awake time this month, against the plan. No parameters.

Reading

describe

Tables with row counts, their fields with types and example or allowed values, and a sample row. Call it first.

Parameter	Type	Required	Notes
`table`	string	no	all tables
`branch`	string	no	`main`; a world, or `name@when` to read the past

sql

Runs SQL as its own session: a transaction must BEGIN and COMMIT within one call. Each result comes back as a table, or a statement’s tag.

Parameter	Type	Required	Notes
`sql`	string	yes	one or more statements
`params`	array	no	JSON values for `$1`, `$2`, …
`branch`	string	no	`main`; a world, or `name@when` to read the past

get

Parameter	Type	Required	Notes
`table`	string	yes
`id`	string	yes	the row’s key
`branch`	string	no	`main`; a world, or `name@when` to read the past

find

Exact filters, plus optional text search (BM25) and vector similarity, best first; the match count, then up to limit rows with scores.

Parameter	Type	Required	Notes
`table`	string	yes
`where`	object	no	`{"field": value}`, all must match
`text`	string	no	words to find in the rows’ text fields
`vector`, `vector_field`	array, string	together	ranks by dot product with the stored vectors
`limit`, `offset`	integer	no	20, 0
`ef`	integer	no	the vector graph’s beam; 0 chooses
`branch`	string	no	`main`; a world, or `name@when` to read the past

Writing

Writes go to the world named in branch: one the agent forked (or main, in development, for an agent without a merge policy).

put

Creates or replaces one whole row. On a SQL table it is checked like an INSERT: columns, types, NOT NULL, unique keys and foreign keys.

Parameter	Type	Required	Notes
`table`	string	yes
`id`	string	yes
`record`	object	yes	the row
`branch`	string	yes	the world to write

delete

Parameter	Type	Required	Notes
`table`	string	yes
`id`	string	yes
`branch`	string	yes	the world to write

Most agents write with sql instead: INSERT, UPDATE, DELETE and migrations on the world.

Worlds

fork

Creates a world, an instant private copy. Returns created branch task-1 (world id …) from main; pass branch="task-1" to work on it.

Parameter	Type	Required	Notes
`name`	string	yes	e.g. the task id
`from`	string	no	`main`; a world, or `name@when`
`meta`	object	no	notes (`owner`, `task`), a declared scope (`may_change`, `tenant`, `max_rows`, `max_deletes`, `intent`), run tags (`run_id`, `prompt_version`, `model`, `tool_schema`), `check_reads`

branches

Lists worlds with their parent and number of changes. No parameters.

set_meta

Merges a JSON object into a world’s metadata; null removes a key.

Parameter	Type	Required	Notes
`branch`	string	yes
`meta`	object	yes

diff

What changed since the fork, row by row: the count first (2 changes on task-1 (leads: 1 deleted, 1 updated, 0 inserted)), deletes first with what they held (- DELETE table/id {row}), then + table/id {row} and ~ table/id field: old -> new.

Parameter	Type	Required	Notes
`branch`	string	yes
`to`	string	no	compare `branch` to this world or moment instead of the fork point
`as_sql`	boolean	no	the change as SQL statements
`readers`	boolean	no	what in the database reads each changed column
`count`	boolean	no	just the per-table counts, and what its merge would send
`limit`, `offset`	integer	no	20, 0

rebase

Takes in what changed in the parent, keeping the world’s own changes on top. Refused on a conflict nothing settles.

Parameter	Type	Required	Notes
`branch`	string	yes
`by_columns`	boolean	no
`rows`	object	no	`{"table/id": "ours" \| "theirs" \| "delete" \| {row}}`
`resolve`	string	no	`fail`, `ours` or `theirs`
`version`	integer	no	only if still at this version

check_reads

For a world forked with check_reads: whether anything it read changed since it forked. Changes nothing.

Parameter	Type	Required	Notes
`branch`	string	yes

checkpoint, rollback

checkpoint names this moment of a world (branch, name); rollback puts the world back to one (branch, checkpoint).

discard

Parameter	Type	Required	Notes
`branch`	string	yes
`cascade`	boolean	no	also every world forked from it

Merging

merge_preview

What merge would do, without doing it: per row, apply or conflict and why, with base, ours and theirs; a summary row per table first, deletes next; a blocked row if a policy or check would hold it; then what reads the changed columns; and the world’s version to merge exactly what it showed.

Parameter	Type	Required	Notes
`branch`	string	yes
`into`, `only_tables`, `only_keys`, `by_columns`, `resolve`, `rows`		no	as for `merge`
`limit`, `offset`, `version`	integer	no	pages; later pages refused if the world changed

merge

Applies the world to its parent and deletes it (with into, only_tables or only_keys, the world stays). Conflicts come back with isError: true and how to settle them; a held merge comes back with the policy’s reasons and, on a production project, the review’s link.

Parameter	Type	Required	Notes
`branch`	string	yes
`into`	string	no	another world to merge into
`only_tables`, `only_keys`	array	no	merge just those; `"table/id"` for keys
`by_columns`	boolean	no	only a column both sides changed conflicts
`rows`	object	no	`{"table/id": "ours" \| "theirs" \| "delete" \| {row}}`
`resolve`	string	no	`fail` (default), `ours`, `theirs`
`version`	integer	no	merge only if still at this version
`target`	integer	no	with rows settled: the target `merge_preview` named
`confirm`	boolean	no	after the server stopped: merge as it is now

a call

{"name": "merge", "arguments": {"branch": "fix-prices", "version": 7}}

History

history

What happened to a world recently, newest first (branch, limit 30).

restore and undo_merge aren’t listed for coding agents on Chronos Cloud: putting data back is a person’s job, from the dashboard or SQL.

Rules and reviews

Tool	Does
`merge_policies`	the policies, and which agent keeps to each
`check_merge_policy`	tries rules on a world’s real changes: `branch`, a policy `name`, and/or `rules` to override; nothing is saved
`reviews`	merges waiting for a person, oldest first
`review`	for a policy’s reviewer agent: `branch`, `verdict` (`approve`, `reject`, `pass`), `reason`
`merge_checks`	the merge checks

Simulations

Tool	Parameters
`simulate`	`worlds`, `prefix`, `script`, `score` (required); `from`, `keep`, `order`, `seed`, `threads`
`replay`	`world` (one a simulation kept); `as` to keep the replay

Errors

A tool that fails answers normally with isError: true and a message saying how to fix the call: a missing parameter, a refusal (with the right the agent lacks), a SQL error (with its SQLSTATE), a merge conflict (with the rows). Protocol errors use JSON-RPC’s: -32700 for a body that isn’t JSON, -32601 for an unknown method.

a failed call

{"jsonrpc":"2.0","id":8,"result":{"content":[{"type":"text","text":"'id' is required: a non-empty string without spaces"}],"isError":true}}

#Protocol

#Project tools