MCP tools

mcue speaks MCP in two places: a local server on your machine, and a persistent hosted endpoint on Hub. Both serve the same tools with the same arguments and the same result shapes, so an agent configured against one works against the other.

The two surfaces

	Local	Hosted
Command	`mcue serve --mcp`	none — always on
Endpoint	stdio, or an authenticated HTTP address	`https://api.mcue.dev/mcp`
Auth	bearer tokens from `mcue token`	OAuth via Hub
Available when your machine is off	no	yes
Reads	local state under `$MCUE_HOME`	accepted Hub state
Requires an account	no	yes, invite-only

Tools

Tool	Kind	Local	Hosted	What it does
`index`	read	yes	yes	The derived portfolio view across projects; `sort`, `expand_lanes`, `focus`
`review`	read	yes	yes	One project's lanes as JSON: status, objective, next action, blockers, signals, plan, drift and latest checkpoint per lane
`resume`	read	yes	yes	Fetch a bounded resume packet for a project lane
`project_state`	read	yes	yes	Read current governed project state
`checkpoint_latest`	read	yes	yes	Read the most recent checkpoint
`checkpoint_history`	read	yes	yes	List checkpoint headers newest first, no bodies; `lane` and `limit` (default 20, max 200)
`checkpoint_read`	read	yes	yes	Read one checkpoint verbatim by the `file` a history row carries, superseded ones included
`drift`	read	yes	yes	Repository drift per lane as JSON; missing or stale evidence reads unknown, never clean
`hub_status`	read	yes	yes	The Hub API and web origins and, per project, its link, sync cursor and pending writes
`closeout`	write	yes	yes	Write a checkpoint and advance governed state
`init`	write	yes	yes	Create a project with project state, decisions log, and default lane
`lane_create`	write	yes	yes	Create a named operating lane inside a project
`lane_close`	write	yes	yes	Retire a lane as done or abandoned, keeping its history
`plan_create`	write	yes	yes	Create the active plan for a lane from a Markdown body
`reconcile`	write	yes	yes	Resolve a lane with multiple unreconciled perspectives

Reads are the common case. closeout is the write that matters — it is the same operation the CLI performs, through the same validator, with the same required fields.

Both servers register their tools from one catalog in mcue's shared core, so a tool, an argument or a result shape cannot change on one without the other. Each server's test suite fails if it drifts from that catalog, and the table above is checked against the local server's live tool list by the site's own check before it ships. Where the two behave differently, the tool's own description says so:

drift — the local server observes each lane's attached repository on the spot; Hub reads the observations a host uploaded with mcue observe <project-id> --upload, and never runs Git itself.
request_id on closeout, lane_create and lane_close — Hub requires it, so a retry after a lost response returns the original result instead of writing twice. The local server accepts it and honours it the same way, but does not require it.
hub_status — locally it reports the Hub this machine is configured for and each published project's sync cursor and pending writes; on Hub every project is linked and nothing is pending.

review, drift and hub_status return JSON. A lane in review whose perspectives disagree carries refusal: needs_reconcile and lists them, instead of picking one; call reconcile to resolve it.

Project selection comes from tool arguments and authorised membership, not from a per-project URL or a separate deployment. One endpoint covers everything you have published.

Connecting a client to the hosted endpoint

Every client asks for the same two things: the endpoint URL and a sign-in. Nothing is installed on the client side, and no token is copied by hand — the sign-in is an OAuth flow that Hub runs in your browser. Menu names move between client releases; the shape does not.

Claude.ai. Open Settings, then Connectors, and add a custom connector. Give it a name, paste the endpoint URL, and save. The first time you enable it in a chat, Claude sends you to Hub to sign in and approve the client.

ChatGPT. Open Settings, then Connectors (Apps in some releases), and create a new connector with the endpoint URL. Adding a remote MCP server currently requires developer mode on the account. ChatGPT sends you to Hub to sign in when you first use it.

Claude Code.

claude mcp add --transport http mcue https://api.mcue.dev/mcp

Then run /mcp inside a session and pick mcue to complete the sign-in.

Cursor, and other clients that read an mcp.json.

{
  "mcpServers": {
    "mcue": {
      "url": "https://api.mcue.dev/mcp"
    }
  }
}

The client detects OAuth from the endpoint's 401 response and opens the sign-in.

Whichever client you use, once signed in it can read and write your own projects. The next section covers how to narrow or revoke it.

Authorisation on the hosted endpoint

A client you connect can read and write your own projects. You approved it at sign-in, on your own account, so it needs no further step before its first save. You can restrict any client to read, or revoke it, in the Hub connection settings at hub.mcue.dev. The same default covers creating a new project with init; a client restricted to read or revoked under Account access cannot.

A client you have restricted to read gets an explicit refusal telling it a write grant is required, rather than a vague permission error it might retry forever.

Projects other people share with you work differently. The owner sets whether agents may write to the shared lane, and when you join you choose for your own agents: write where the share allows it, unless you pick read.

Grants are per client, set on one project or across your account, and changes take effect immediately. Revoking a client on a project stops its access there; it does not delete project state.

What the hosted endpoint will not do

Some operations require an authenticated browser session and cannot be performed by any OAuth client, whatever its access:

deleting a hosted project
deleting your account
administering grants for other clients

These live in the Hub UI behind typed confirmation. An agent cannot be talked into performing them.

Authenticating a local HTTP client

mcue token issue          # issue a 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

The plaintext is shown once at issue. list never prints it — if you lose a token, rotate rather than trying to recover it.

Provenance

Every write through either surface records the actor, the device, and the substrate that produced it. That is what makes agent writes reviewable after the fact:

mcue audit

A checkpoint written by an agent through an MCP client is distinguishable from one you typed, in the audit log and in the checkpoint's own front matter.

Teaching an agent the rules

mcue agents-snippet >> AGENTS.md

Emits the canonical access-rules snippet. It works equally in CLAUDE.md or any other instruction file your client reads, and it is worth adding — agents that know when to close out behave markedly better than agents guessing.

Over MCP the server teaches this itself: both the local server and the hosted endpoint send the contract as server instructions in the initialize handshake and expose it as the mcue://agents resource (CLI v0.14.0 and later). The repo file remains useful for shell-based agents and for clients that discard server instructions; mcue agents-snippet --mcp prints the MCP variant.

Give agents your state — the walkthrough, including local client setup.
Publish to Hub — getting the hosted endpoint.
Authority and conflicts — what happens when an agent and you write at once.