Coding agents (MCP)

#The MCP address

Every project is reached through one MCP address over streamable HTTP, with the project named in it: https://…/?project=prj_…. The dashboard’s Connect page shows yours, with the exact line or file for each tool below, and chronos init writes it into .mcp.json for you.

The server lists three tools of its own (setup_project, use_project, usage) and every tool of the project’s database: describe, sql, fork, diff, merge, and the rest. See MCP tools.

#Per tool

Claude Code

claude mcp add --transport http chronos "https://…/?project=prj_…"

Or run chronos init in the folder: it writes .mcp.json, which Claude Code reads, and a block in CLAUDE.md that tells it how to work with worlds.

Cursor

{  "mcpServers": {    "chronos": { "type": "http", "url": "https://…/?project=prj_…" }  }}

Codex

[mcp_servers.chronos]url = "https://…/?project=prj_…"

VS Code

{  "servers": {    "chronos": { "type": "http", "url": "https://…/?project=prj_…" }  }}

Windsurf

{  "mcpServers": {    "chronos": { "serverUrl": "https://…/?project=prj_…" }  }}

Any other MCP client

Add an HTTP (streamable HTTP) server with the address. Clients that can’t do OAuth can send an API key instead, as Authorization: Bearer ck_… (made by chronos cloud login, kept in ~/.config/chronos/cloud.toml). Clients that run in a browser can call it too: the endpoint allows any origin, since every call carries a bearer token and never a cookie.

#Signing in

The first time the agent calls a tool, the server answers 401 with where to sign in, and the client runs OAuth 2.1 as the MCP authorization spec describes: it registers itself (dynamic client registration), then opens your browser with a PKCE challenge.

1. You sign in to Chronos, if you aren’t already.
2. A consent page names the program asking (as it registered itself), what it will be able to do (create projects and databases, read and change their data as you), and the address it returns to. Allow it only if you just added Chronos to that program yourself.
3. Allow sends the browser back to the program with a one-time code, which it trades for tokens. Cancel sends it back refused.

To stop a program, remove the Chronos server from it: well-behaved clients revoke their token as they go (/oauth/revoke), and an unused access token expires in 30 days. Revoke on the project’s Agents page disables the agent’s identity on that database and drops its stored token; the person’s next call makes a fresh one, so it rotates the agent’s secret rather than shutting the person out. To shut a person out, remove them from the org (see Teams).

#Which project

Each call works on one project, the first of these that is set:

1. the project use_project or setup_project set earlier in the same MCP session;
2. ?project=prj_… on the address, or an X-Chronos-Project header (what chronos init writes);
3. your only project, if you have exactly one.

With none, database tools answer with what to do: call setup_project with the folder’s name and git remote get-url origin. It finds the project that remote belongs to (so a clone, or a teammate, gets the same database), or makes one, and returns DATABASE_URL and the files to write. A project named in the address that isn’t in your org is ignored, as if none were named.

#Who the agent is

Each person has one agent on each project’s database, claude-<login>-<project>, made the first time their client calls a database tool. Every program a person connects acts as that one agent, and the Agents page lists which programs (and versions) have used it.

Give the agent a merge policy to let it land small, safe changes in either mode, and hold the rest: see Merge policies.

#What the agent is taught

The server’s instructions, and the block chronos init writes into CLAUDE.md (and AGENTS.md if there is one), teach one loop:

1. describe the schema, then fork a world for the task;
2. make schema and data changes there with sql (never on main);
3. run the app’s tests against the world;
4. show the diff, deletes first;
5. merge. If a policy holds it, stop and report the world and the reasons; a person decides.

#Troubleshooting