Give agents your state

An agent that cannot see what you were trying to do will confidently redo work you already abandoned. mcue exposes the same validated read and write surface over MCP that the CLI uses — not a second, looser path into your state.

Run the local server

mcue serve --mcp

That speaks MCP over stdio, which is what most desktop clients expect. It runs entirely locally and makes no outbound request.

For clients that need HTTP instead of stdio, mcue serve also exposes an authenticated HTTP surface. Run mcue serve --help for the current flags — the address and transport options are the two you will care about.

Connect a client to the local server

Desktop clients launch the server themselves over stdio. Each one needs the same line: the command is mcue, the arguments are serve --mcp.

Claude Code.

claude mcp add mcue -- mcue serve --mcp

Claude Desktop, in claude_desktop_config.json, and Cursor, in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mcue": { "command": "mcue", "args": ["serve", "--mcp"] }
  }
}

Browser clients such as Claude.ai and ChatGPT cannot launch a process on your machine. They connect to Hub's hosted endpoint instead — see Connecting a client to the hosted endpoint.

Authenticating an HTTP client

The HTTP surface is bearer-authenticated, and mcue manages those tokens for you:

mcue token issue          # issue a new bearer token
mcue token list           # ids, scopes, status — never the plaintext
mcue token rotate <id>    # revoke and reissue with the same scope
mcue token revoke <id>    # revoke by id

mcue token list deliberately never prints the plaintext token. If you lose one, rotate it rather than trying to recover it.

Teaching the agent the rules

Agents behave much better when the repository tells them how mcue is meant to be used. mcue emits that snippet for you:

mcue agents-snippet >> AGENTS.md

The same snippet works in CLAUDE.md or any equivalent instruction file. It describes the access rules — what the agent may read, when it should close out, and what it must not invent.

The snippet opens with a short procedure the agent must run before any project work: find the project, discover its lanes, select the lane by what you asked for now, read that lane's packet, and only then open the code. It also says that your current request decides the work — a recorded next action is context, not an instruction — and that local and Hub state are separate sources whose disagreement must stay visible.

Two habits make lane fit visible without a checklist. The agent says in one line which lane it is using when it selects or switches, so a wrong assumption surfaces before the work. And before proposing a closeout it compares the work with the lane's objective: it does not stretch the objective to fit, it routes the closeout to the lane the work belongs to, and a session that produced work for two streams gets two closeouts. To make that selection cheap, mcue review and mcue index --expand-lanes print each lane's objective.

Where the file goes, and how to check it loaded. Codex, Cursor, and Aider read AGENTS.md; Claude Code reads CLAUDE.md. Put the snippet in the file your client reads, at the root of the repository the agent starts in. A file at a workspace root is not loaded when the agent starts inside a child repository, so each repository that carries mcue state needs its own copy, or a one-line file that points at the root one. To verify, open a fresh chat and ask: "what is the first thing you do before project work here?" The answer should be the start-here procedure, given without a search. If the agent searches the repo to answer, the file is not being loaded.

An agent connected over MCP does not need the file. Since v0.14.0 the server sends the same contract as MCP server instructions during the handshake and serves it as the mcue://agents resource, so a client that has never seen mcue learns the vocabulary and the read-first, close-out-at-ship rules before its first tool call. The hosted Hub endpoint carries the same instructions. Keep the repo file for agents that reach mcue through a shell rather than MCP tools, and for clients that ignore server instructions — mcue agents-snippet --mcp prints the MCP variant for those.

What the agent can do

The local server and Hub's hosted endpoint expose the same tools:

Tool	What it does
`index`	the portfolio view across projects
`review`	one project's lanes as JSON, with signals, plan and drift per lane
`resume`	fetch a bounded resume packet for a lane
`project_state`	read current governed project state
`checkpoint_latest`	read the most recent checkpoint
`checkpoint_history`	list checkpoint headers, newest first, without bodies
`checkpoint_read`	read one checkpoint verbatim, superseded ones included
`drift`	check whether the repository moved since the lane's checkpoints
`hub_status`	where this mcue connects to Hub, and each project's sync state
`closeout`	write a checkpoint and advance state
`init`	create a project with its state files
`lane_create`	create a named lane
`lane_close`	retire a lane as done or abandoned
`plan_create`	create the active plan for a lane
`reconcile`	resolve a lane whose perspectives diverged

Reads are the common case. closeout is the one write that matters, and it goes through the same validation the CLI uses — an agent cannot write state the CLI would have rejected.

Full detail is in the MCP tools reference.

Provenance

Every write records which actor and which substrate produced it. When you later read a checkpoint, you can tell whether you wrote it or an agent did, and through which client. That is what makes it safe to let an agent close out at all: the record stays attributable.

mcue audit

reads the local audit log.

Local server or hosted endpoint

The local server needs your machine to be on. If you want an agent to keep working against accepted state while your laptop is shut, that is what Hub's persistent endpoint is for — see Publish to Hub.

The tools above are the same in both cases, so moving from one to the other does not change how the agent is configured beyond the endpoint and its credentials. The MCP tools reference lists the few places the two behave differently.

A release can add a tool. Clients take a server's tool list when a conversation starts and keep it for that conversation, so a tool added by a Hub deploy shows up in the next conversation, not the one already open — refresh the connector if your client caches the list across conversations. To see which contract a Hub serves, read its server version in the initialize handshake or the hubcore field of GET /readyz; both carry the mcue release it was built against.

A caution worth stating

An agent with write access can close out on your behalf. That is useful and it is also a way to fill your history with plausible, generic checkpoints that say nothing. Keep agent closeouts for genuine session boundaries, and read them occasionally to check they are worth keeping.