Use vrtmv with AI
An AI assistant or coding agent can work with vrtmv through the Model Context Protocol (MCP). vrtmv has two MCP servers. Neither has client-specific code.
vrtmv mcp, themcpsubcommand of thevrtmvbinary. The client starts it on the client's own host, which must be an x86-64 Linux host. It can assess a host, plan a migration, ask questions and file findings. Claude Code uses it, and so do the other command-line and editor clients on this page.- The hosted server,
https://mcp.vrtmv.com/mcp. A client connects to it over HTTPS. It covers your account and the Translation Index, but it cannot reach your hosts. Claude Desktop on macOS and Windows, claude.ai and ChatGPT use it, because they cannot start the Linux binary.
Before you start
These steps set up vrtmv mcp. The hosted server needs none of them.
-
Install and verify the binary. See Installation. The MCP server is the
mcpsubcommand of that binary, so it is not a second download. The binary is built for x86-64 Linux, so the client must run on such a host too. -
Store your API token as the OS user that runs the client. See Authentication:
vrtmv auth <token>The client configs on this page carry no token.
-
Print the server entry. It holds this binary's absolute path:
vrtmv mcp --print-config{ "mcpServers": { "vrtmv": { "args": ["mcp"], "command": "/opt/vrtmv/vrtmv" } } }The examples below use
/opt/vrtmv/vrtmv. Put your own path in its place.
vrtmv mcp is a local server. The client starts it on the client's host and talks to it over stdin and stdout, so workload data stays on that host. The tools it offers are listed on the mcp page.
Claude Code
claude mcp add --scope user vrtmv -- /opt/vrtmv/vrtmv mcp
claude mcp list
claude mcp list starts the server. Once vrtmv auth has stored a token, it prints vrtmv: /opt/vrtmv/vrtmv mcp - ✔ Connected. With no token it prints ! Connected · tools fetch failed instead (see Check that it works). --scope user makes the server available in every project. Without it, Claude Code adds it to the current project only.
Claude Desktop on macOS or Windows, and claude.ai
Add the hosted server as a custom connector. On a Pro or Max plan:
- Open Customize → Connectors, click + Add, then Add custom connector.
- Enter a name, such as
vrtmv, and the URLhttps://mcp.vrtmv.com/mcp, then click Continue. - Under OAuth client, choose Register automatically. That is the only option the vrtmv server supports. Leave the other settings as detected, then click Add.
- Connect it. A vrtmv sign-in page asks for an API token from your account. The connector never sees that token: the server keeps it and gives the client a token of its own.
A Free plan can have one custom connector.
On a Team or Enterprise plan, members cannot add custom connectors. An Owner or Primary Owner adds it once for the organization: Organization settings → Connectors → Add, then Custom → Web, with the same name, URL and Register automatically choice. Each member then opens Customize → Connectors, finds vrtmv in the list, and clicks Connect.
A connector added in claude.ai is also there in Claude Desktop when you sign in with the same account.
The hosted server's tools cover your account (usage, statements and API tokens) and the Translation Index (package, service and config translations, advisories and database upgrade paths). The Translation Index tools are metered, and their descriptions say so. vrtmv_usage records a usage event, which can count against your quota. The server cannot reach your hosts, so it cannot assess or migrate them. For that, run vrtmv mcp on a Linux host, from Claude Code or another client on this page. If the hosted server restarts, the client asks you to sign in again.
Claude Desktop on Linux (beta)
Claude Desktop for Linux is a beta. It supports Ubuntu 22.04 or later and Debian 12 or later, not Fedora or RHEL. The vrtmv binary is built for x86-64 only, so this works on an x86-64 machine with one of those systems. There, Claude Desktop can start vrtmv mcp itself. Install it with the MCP Bundle, or by hand after the steps in Before you start.
With the MCP Bundle. Each release includes an MCP Bundle, vrtmv-<version>-x86_64-unknown-linux-musl.mcpb, next to the tarball. It is signed and listed in the release's .sha256 file. It holds the same vrtmv binary as the tarball.
- Download it from your account's releases page.
- Verify it as you verify the tarball, with
.mcpbin place of.tar.gz. - Open the file in Claude Desktop. The install asks for an API token, which is optional. Leave it empty to use the token that
vrtmv authstored for the user that runs Claude Desktop.
The bundle installs on x86-64 Linux only, the one platform the binary is built for.
By hand. Open Settings → Developer → Edit Config. In the file that opens, add the vrtmv entry from vrtmv mcp --print-config under mcpServers, then save the file and restart Claude Desktop.
Cursor
Paste the output of vrtmv mcp --print-config as it is into ~/.cursor/mcp.json to use the server in every project, or into .cursor/mcp.json to use it in one project. If the file already lists servers, add the vrtmv entry to its mcpServers.
VS Code (GitHub Copilot)
code --add-mcp '{"name":"vrtmv","command":"/opt/vrtmv/vrtmv","args":["mcp"]}'
This command adds the server to your VS Code user profile. To add it to one workspace instead, put it in .vscode/mcp.json. That file names the key servers, not mcpServers:
{
"servers": {
"vrtmv": { "command": "/opt/vrtmv/vrtmv", "args": ["mcp"] }
}
}
Copilot Chat uses MCP tools in agent mode.
Codex CLI
codex mcp add vrtmv -- /opt/vrtmv/vrtmv mcp
The command writes this to ~/.codex/config.toml, which you can also edit by hand:
[mcp_servers.vrtmv]
command = "/opt/vrtmv/vrtmv"
args = ["mcp"]
Gemini CLI
gemini mcp add -s user vrtmv /opt/vrtmv/vrtmv mcp
The command writes the --print-config entry under mcpServers in ~/.gemini/settings.json. Without -s user, it goes into the project's .gemini/settings.json.
Check that it works
When the client starts vrtmv mcp, it asks for the list of tools. If the OS user that runs the client has no token, the server refuses that request. The client then shows no vrtmv tools, and its MCP status or log shows vrtmv mcp: no API token. In Claude Code, claude mcp list prints:
vrtmv: /opt/vrtmv/vrtmv mcp - ! Connected · tools fetch failed — vrtmv mcp: no API token — run `vrtmv auth <token>` or set VRTMV_API_KEY
Run vrtmv auth <token> as that user, then restart the server in the client. Setting VRTMV_API_KEY in the client's server entry also works, but then the token is stored in that file.
Once the client lists the vrtmv tools, ask the agent to call vrtmv_whoami. It should return your account. The hosted server has no vrtmv_whoami. There, ask for vrtmv_account.
ChatGPT
ChatGPT connects only to remote MCP servers over HTTPS, so it cannot start vrtmv mcp. Add the hosted server as a custom MCP server instead. We tested these steps in ChatGPT on 2026-11-12:
- Open Plugins, click Add, then Add custom MCP server.
- Enter the URL
https://mcp.vrtmv.com/mcp. - For authentication, choose OAuth and leave the client ID empty. ChatGPT registers itself with the vrtmv server automatically.
- Sign in. A vrtmv sign-in page asks for an API token from your account. The connector never sees that token: the server keeps it and gives ChatGPT a token of its own.
- Start a new chat and select the vrtmv connector. Ask it to call
vrtmv_account. It should return your account.
The connector has the hosted server's tools, as in claude.ai: your account and the Translation Index. It cannot reach your hosts, so it cannot assess or migrate them. For that, run vrtmv mcp on a Linux host, from Claude Code or another client on this page.
Tell a coding agent about vrtmv
A coding agent reads standing instructions from a file in the repository, AGENTS.md for most agents. Paste this section into that file, in a repository whose hosts you migrate with vrtmv:
## vrtmv
Hosts are assessed and migrated with vrtmv (https://docs.vrtmv.com). The `vrtmv` MCP
server is configured for this agent.
- Start with `vrtmv_assess` on a `root` path, an `image` or an `ssh` target. It runs
locally, is free and sends nothing. Pass paths, never file contents.
- Run `vrtmv_migrate` with `preflight=true` first. A real migrate needs `confirm=true`
and bills a seat: ask the user before you run it.
- `vrtmv_verify` bills a seat too and needs `confirm=true`. Ask the user before you
run it.
- Never run `vrtmv auth`, and never print, log or commit the API token.
- Commands and flags: https://docs.vrtmv.com/commands/overview.html
- An index of every docs page: https://docs.vrtmv.com/llms.txt
The docs index for assistants
/llms.txt lists every page of this site with a one-line summary. It follows the llms.txt format, so an assistant can find the right page without crawling the site.
New to vrtmv? Sign up free for 10 migrations, or get a free assessment: run it on one hard host and we review the parity report with you.