Set up your agent

Connect Claude Code, or another agent that speaks MCP, to your Workover documents. You install the Workover CLI, sign in once through your browser, then add the Workover MCP server to your agent. The CLI and the MCP server share that one sign-in.

Before you start: you need Node.js 20 or later with npm, a Workover account you can sign in to in your browser, and an agent that can run a local MCP server.

1. Install the CLI

npm i -g @workover/cli

This installs the workover command.

2. Choose what your agent may do

workover login always grants two permissions, or scopes: reading your documents, and suggesting changes for you to review and accept. For most people that is enough. Add a flag only for the extra power you actually want:

If you want your agent to…	Add
Read, search and create documents, and propose edits you accept or reject	Nothing
Edit documents directly when you ask, with no suggestions to review	`--write`
Run Workover AI from the terminal: drafts, `doc reshoot`, `doc verify`, `eval`	`--draft`
Add rules to your style guide	`--rules`

Also pass --client "<name>" to name the connection, for example --client "Claude Code". The name appears on the approval screen and under Connected devices, and the default is “Workover CLI”.

You do not need --publish for an agent. Neither the CLI nor the MCP server publishes; that scope only unlocks the publishing routes of the HTTP API.

Warning: --write lets the agent replace a document’s text with nothing for anyone to review, so anything it leaves out is deleted. --draft spends AI credits and lets Workover sign in to the app you connected for screenshots. --rules lets it change the style guide for everyone in the workspace. Grant these only to an agent on a machine you trust.

The CLI and the MCP server use the same token, so choose the flags for everything you plan to do with either. The CLI and MCP reference lists what each scope unlocks.

Run workover login with the flags you chose, for example:

workover login --client "Claude Code"

The terminal prints your login code and a link, and opens your browser.

In the browser, sign in to Workover if you are not already signed in. If the page asks for a code, type the code from your terminal and click Continue.
Check the approval screen. Its heading names the connection, for example Approve Claude Code? Make sure the code on screen matches the one in your terminal, and read the list of permissions. Permissions marked ! reach further than reading and suggesting.
Click Approve. The page shows Device connected, and the terminal confirms that you are signed in.

Only approve a code from a workover login you just ran yourself. If you did not, click Deny.

4. Add the MCP server to your agent

In Claude Code:

claude mcp add workover -- npx -y @workover/mcp

In another MCP client, add a local (stdio) server whose command is npx with the arguments -y @workover/mcp.

Start a new agent session afterward. A newly added MCP server is not available in the session that added it.

5. Try it

Check the sign-in, then find a document to work on:

workover whoami
workover projects
workover doc list --project <projectId>
workover doc read <docId>

whoami shows the server you are signed in to and the start of your token. projects lists the projects you can reach with their ids, and doc list prints each document’s id as #123.

Then ask your agent something like “Read Workover document 123 and tighten the introduction.” Without --write, its changes arrive in the document as suggestions you accept or reject.

Change your scopes later

Scopes are fixed when a token is created. To add one, run workover login again with the new flags and approve the new request. Signing in again replaces the token stored on this machine but does not revoke the old one, so revoke the old row under Connected devices; see Access tokens. Then restart your agent session, because the MCP server reads the token when it starts.

Troubleshooting

“The code expired.” Codes last 10 minutes. Run workover login again.
“Approval was denied.” Someone clicked Deny. Run workover login again and approve it.
The browser did not open. Copy the link printed after “Approve it here:” into your browser.
The agent says “Not signed in to Workover.” Run workover login, then restart your agent session.
A command or tool returns a permission error. Your token lacks the scope it needs. Sign in again with the flag the reference lists for it.