MCP tools

Rift's MCP server at https://fixedlabs.dev/mcp offers the agent the tools and resources on this page. Every call runs as the user whose token it carries, and is authorized against that user's membership and role at the moment it runs: members read, admins change, and a box is reached only through the task that holds it. This page is the whole surface.

Tasks

A task is what boxes belong to; its handle, task_<id>.<secret>, goes on every box call. See Tasks.

• rift_task_new name — opens a task and holds it. Answers the handle.
• rift_task_ls — your open tasks: id, name, who holds it or free, last activity, its boxes. No handles.
• rift_task_attach task, takeover? — a fresh handle for a task: a free one, one whose holder has been quiet for half an hour, or with takeover any of yours. The previous handle dies.
• rift_task_release task — gives the lease up, boxes kept.
• rift_task_close task — closes the task and destroys its boxes.

Boxes

• rift_vm_new task, repo, ref — a box at a watched ref's head, in the task: a warm one if the pool has it, else a cold start. Parks up to 30 s for it to run, and says to poll rift_vm_ls if it isn't yet. Answers the VM's id, its name and its status.
• rift_vm_ls task — the task's VMs: id, name, status, repository, ref, commit.
• rift_vm_destroy task, vm — destroys one, with its checkout and its state. An agent that makes a box for a short job, for example a subagent's check or a test run, destroys it when the job is done.
• rift_vm_suspend task, vm — parks one. A parked box keeps its checkout and its state, and as a rule its processes; the next call on it resumes it. A running box costs money, so the agent suspends each box it is not using.
• rift_bash task, vm, command, timeout, block_for — runs a shell command in the box's jail. timeout is the command's run time in seconds, from 1 to 259200 (72 hours): the box stops the command when it passes. block_for is how long the call waits for the command to end, in seconds, from 0 to 45. Both are required. The command runs until it ends, whether or not the call still waits for it. rift_vm_new and rift_vm_ls say what persists on each VM. What needs GitHub is a verb — verbs lists them — see Inside a box.
• rift_read task, vm, path — a file, as the jail sees it.
• rift_write task, vm, path, content — writes one.
• rift_output task, commands, block_for — waits for commands and reads their output. commands holds 1 to 4 commands of one box, each once: its id and the byte offset to read from (0, or the next_offset of the last answer). The call waits up to block_for seconds, until the first of the commands ends, then gives the output of each from its offset. One answer gives at most 64 KiB of output, shared equally by the commands: 64 KiB for one command, 16 KiB each for four.
• rift_stop task, id — stops a command. A command that has not started does not run. A running command is killed; the answer gives its end, or says that the stop is requested.

A VM has an id and a name. The id is b- and 24 hexadecimal characters, and no other VM has it. The name is for a person to read: the short name of the repository, the ref and a number, for example app-main-3. Two VMs can have the same name. The vm argument takes the id, or a name that only one VM of the task has. When two or more VMs of the task have that name, Rift refuses the call, and the answer gives their ids. A VM made before Rift gave ids has its name as its id.

A box runs up to 4 commands at once. A rift_bash, rift_read or rift_write call while 4 commands are open does not run, and the answer names each open command by its id, with the rift_output and rift_stop calls that take that id. Rift parks a box that is unused for 30 minutes. A box with an open command does not park, and rift_vm_suspend refuses to park it.

Each of these five tools answers in less than 55 seconds after Rift receives it, also when the box must resume first. A command's id is the box's id and a number, <vm>.<n>. The answer starts with one of three statuses:

• finished: the command ended, with its exit code. The reason says when its timeout or rift_stop stopped it.
• did not run: the command never ran and never will, and the answer says why — for example a box that was destroyed, or an agent that did not take it within 10 minutes.
• has not finished: the command is waiting to start, or runs. The answer gives its id and the exact rift_output call that reads on. Do not send the command again. A command that Rift lost track of has this status too, with the reason lost: its box's agent was silent or restarted, and it may have run in part.

Each answer that gives output gives the next offset and the output's total size; while bytes remain, it gives the exact rift_output call for them. Output is cut at character boundaries. Rift keeps the last 8 KiB of the output of each of the last 64 commands of a box. Output before those 8 KiB is read from the box; a parked box is not resumed for it, and the answer says which bytes need the box awake. rift_read and rift_write give their content in their own answer.

The answer also carries these fields as structuredContent: status, reason, command, exit, output, next_offset and size.

A rift_output answer on two or more commands gives each command's status and output in its text, then the exact rift_output call that waits on the commands that are open or whose bytes remain, each from its next offset: call it again until every command ended and its output is read. Its structuredContent has commands: for each command, in the order of the call, its status, reason, command, exit, output, next_offset and size. It also has ended: the ids of the commands whose record ended, including commands that did not run and commands that Rift lost track of. An id that Rift has no record of is not in ended, although its status is "did not run".

Your account and organizations

• rift_whoami — one document: who you are, whether GitHub is connected for pushes, your invitations, your personal organization and each team with its members, GitHub accounts and watched refs — and at the end a line per gap with the tool that closes it, or ready with the rift_vm_new to call. The agent's checklist.
• rift_org_new name — makes a team with you as its admin.
• rift_org_invite org, email, role? — a team's admins. Invites someone; they get an email, which lets them make an account if they have none.
• rift_org_accept org — accepts a pending invitation.
• rift_account_invite email — the platform admin. Lets someone make an account.
• rift_waitlist since?, limit? — the platform admin. The people on the waitlist, oldest first, one line each: when they joined, email, name, organization, note, and the teams that invited them. since is a UTC date or an instant; limit is 50 by default and 500 at most. rift_account_invite admits a person.
• rift_github_connect org — admins. The App's install URL — personal for your own GitHub user, a team for a GitHub organization; the agent shows it and waits for you.
• rift_github_enable org, account — admins. Rift on for an installed account.
• rift_github_login — the device flow for your own GitHub account, one step per call: first the URL and code, then the check, which names the GitHub user. Needed before rift_github_connect personal, which connects only that user.
• rift_repos org — members. Every repository the App covers, its account, enabled or not, and its watched refs: for each, the warm count, how many VMs are ready, the head, and the last failure at the head with its whole text.
• rift_watch repo, ref, warm? — admins. Watch a branch, keeping warm boxes at its head; one by default.
• rift_unwatch repo, ref — admins. Stop watching a branch: its warm VMs drain, and no new VM can be claimed on it. A VM an agent holds runs on until its task closes.

Some actions have no tool, by design. An admin sets and removes a repository's secrets on its Secrets page in the app at https://fixedlabs.dev/app, so a value never goes through an agent's transcript. In the app, you also revoke an MCP token, disconnect your GitHub account and decline an invitation, and an admin disables a GitHub account. These actions are not necessary to get a box.

Feedback, and the docs

• rift_feedback items — drafts feedback for Fixed Point Labs: one to ten items, each a text, a category (bug or improvement) and optional context for the engineer, added to your feedback draft. Answers the link to your feedback page, where you approve and submit; nothing is sent until you submit there. Each call adds to the same draft, and the link is always the same. See Send feedback.
• rift_docs — the URL of this documentation, and the URL of every page, for the agent to point you at.
• rift_audit [task] [vm] — the URL of the audit: what your agents did, call by call and verb by verb. With task, that task's; with vm, that box's; with neither, every task you may read. It answers a link and nothing else; you open it signed in, and it shows what you may read — your own tasks, and your organizations' if you are their admin.

Resources

• rift://onboard — the walk from a fresh account to a first box, for the agent: call rift_whoami, do the next missing thing, call it again.
• rift://nix-guide — the fixed-labs.rift expression: the contract, a complete example, and the lifecycle from an edit to a fresh box.
• rift://feedback — when to offer feedback, when not to, and what a good item says.

Errors

A refused call answers with a reason that names the tool that mends it — a missing handle says rift_task_new opens one, an unwatched ref says which rift_watch to ask an admin for, a held task says who holds it and that rift_task_attach with takeover takes it. A tool given a wrong argument set is refused before it runs, with the missing names.