Workspace → External agents connects another assistant to one authorized VersoFold project. The Model Context Protocol (MCP) exposes app operations so source changes, compilation, research records and review can use the same guarded services as the built-in agent.
Open the same page from Settings → AI & agent → External agents, from Connect an agent at the bottom of the agent panel's model menu, or from Conversation actions → Agent settings in a connected-agent conversation. The page has Agents & apps, Brief & scope, and Completion & evidence.
Chat with Claude Code, Codex or another installed agent
Agents installed on your computer appear in the agent panel's Choose model menu, under Connected agents, next to the VersoFold agent's models. Pick Claude Code (your Claude subscription) or Codex (your ChatGPT subscription) and the panel switches to that agent; pick a model again to switch back. Inside a connected chat the same menu lists that agent's models first, then the other agents and the VersoFold agent's models. One conversation history holds both kinds of chat.
The same agent panel is available in the editor, PDF reader, reading desk, and reference library. The selected document, passages, and suggested prompts provide the context; model selection, history, and approval controls work the same way. Library conversations use library tools without attaching a manuscript.
Claude conversations default to Latest Claude Opus, using the newest Opus reported by Claude Code. Claude account default is a separate choice and can point to an older model. Select an exact version to keep using it. Choose visible models, at the bottom of the model menu or under Settings → External agents, lets you show or hide choices, add a model ID, and Refresh models. These visibility choices apply across workspaces and readers. The selected model stays visible until you choose another. If a new model is missing, update Claude Code and refresh.
VersoFold asks Claude Code and Codex which models your account offers and shows their names. Each reply's header names the model that actually answered, and Usage shows the latest one.
The menu says when an agent's program is not on this computer. Choosing it then shows how to install it and sign in, with a Check again button. Settings → External agents lists the same agents with their status and a Chat button; Add another agent registers any Agent Client Protocol (ACP) program, such as Gemini CLI, by its executable and launch arguments.
The connected chat has the composer you know: the + menu attaches images and text files, the passage you selected, and prompts from the prompt library. Models, thinking, project mode, approval and writing style sit below the message. Conversation actions → Conversation options holds the reference-library and public-web switches for that chat.
Use VersoFold from another app
Under Use VersoFold from another app, Add next to Claude Code, Codex, Claude Desktop or Cursor creates a connection to this paper and writes it into that app's MCP settings: there is no configuration to copy. Claude Code keeps it with this paper's folder, so running claude there finds VersoFold's tools. Codex, Claude Desktop and Cursor have one global list, so adding a second paper moves the entry to that paper. Claude Desktop needs a restart to load it. VersoFold keeps a backup of an app's original config file (….versofold-backup) the first time it edits it, and never overwrites a file it cannot read. Remove (or Disconnect in the connection list) revokes the key and takes VersoFold out of the app again.
For any other MCP client, Another MCP app creates a configuration with a private key to paste into its settings. A cloud client uses Agents on the web, the separate remote gateway with its own authorization; a reviewer share link is not an MCP connection.
Available models, effort controls and native modes depend on each runtime and account.
Avoid copying account credentials into a project. VersoFold's runtime adapters use their supported authentication paths and do not treat subscription credentials as API keys.
Grant only the intended scope
New connections can read and edit the paper, use your reference library and search and read public websites. Every write is guarded, journaled and undoable, and follows the connection's approval mode. Narrow any of this when you create the connection, or later in the connection list: each existing connection has its own Project access, Approval, Reference library and Public web controls, and changing them keeps its key, so the client needs no new configuration. The connection stays bound to its original project even if you open another workspace.
In a connected chat, Project mode chooses Edit (the default), Plan or Discuss, and Conversation options holds the library and web switches. New connections can above the app list sets the access for the next app you add.
If an agent reaches for something its connection was not given — an edit in a read-only connection, the library, the web — the call becomes an access request instead of failing: “Claude Desktop asks for edit access to this project”. Allow it in one click in the External agents panel, or inline in a connected chat; the connection keeps that access from then on and the agent retries the same step. Declining is remembered, so the agent is not asked again; change the connection's controls to grant it later. A client that asked for read-only access when it connected keeps that ceiling.
Approval choices govern requests within those grants, with the same table as the built-in agent: Manual asks before anything that is not a read; Accept edits lets paper edits, library records and web reads run and asks before commands, files outside the paper, pushes, preference changes and author decisions; Full access asks for nothing. With Claude Code and Codex, Auto uses the runtime's own reviewer. None of them grants unrelated workspaces, account administration or proposal acceptance.
Some runtime capabilities are deliberately restricted to VersoFold tools. ACP programs are external executables and are not made into an operating-system sandbox by MCP permissions; choose a program you trust and review native requests separately.
A productive first request
Ask the assistant to read the workspace context, inspect the relevant source and explain its intended change. It can discover tools by topic rather than guessing endpoint names. Large tool catalogs and results are paginated; a client needs to follow continuation information.
Example: “Read the current methods section and page budget. Propose a clearer organization, preserving every experimental setting. Stage a multi-file restructuring for my review.”
The documentation tools are available here too. They follow the same on-demand policy as the native agent: use the handbook when explicitly requested or when stuck on a specific app capability, not as routine startup reading.
Review actions and proposals
Source reads return locations and current state. Guarded edits check hashes and unsaved buffers. Larger proposals can compile in an isolated copy before acceptance. Open the proposal's before/after source and PDF, then accept or reject it in VersoFold.
An approval_required or input_required response means the action has not happened. Review the exact request in the app — an access request, a tool approval or a question. Connected chat resumes after your answer; a standalone client retries the identical call. An approval_denied or access_denied response means you declined, and the agent must not repeat the action with changed arguments to avoid the decision.
Activity records identify completed operations. Source-edit Undo applies only while its recorded edited state still matches; other domain operations have their own revision/history controls.
Stop, disconnect and resume
Stop ends the active runtime turn and revokes its current connection as implemented by the adapter. Disconnecting prevents future tool calls and requests cancellation. A write that already completed remains applied.
Runtime conversations have their own saved history and IDs. Supported clients resume their saved session; others may use a bounded recap. Interrupted turns are not automatically replayed. Deleting VersoFold's transcript does not necessarily delete a runtime's own external history.
Before retrying after a lost response, inspect the current source or domain record. This avoids creating duplicate work when the first action succeeded but its result was interrupted.