Connect an agent

Rivtor is one MCP server. Connect it once with an API token and your agent can deploy, read logs, set secrets, roll back and query the database, in any project.

Get a token

Create a token at /dashboard/tokens. Tokens start with rvt_, are shown once, and can be revoked there at any time. Every request authenticates with:

header

Authorization: Bearer rvt_...

In the snippets below, replace rvt_... with your token.

Remote or local

Both servers expose the same tools. They differ in how deploy gets your code.

Remote and local MCP servers compared
	Remote (HTTP)	Local (stdio)
Address	`https://api.rivtor.com/mcp`	`npx -y rivtor mcp`
deploy takes	`project` (required), then one source: `git_url` (+ `ref`), `starter`, or `files` (a map of path to content, up to 2 MB in total). Also `dry_run`, `env` and `wait`	`path`, plus optional `project` (default: `rivtor.json`, else the folder name), `dry_run` and `env`. Packs the folder (respecting `.gitignore`; `.env` files are never uploaded) and uploads it as a tarball, up to 300 MB
Use it when	The agent has no filesystem, or deploys from a Git repository	The code is a folder on your machine (most coding agents)
Needs	Nothing installed	Node.js 20 or later
Other differences	`env_set` takes `set` on remote and `vars` on local. `db` has `tables` and `export_url` on remote, `export` (to a local file) on local. `upgrade` defaults to the next plan, yearly, on remote and to Hobby, monthly, on local. Every argument is on MCP tools.

Claude Code

Remote server, one command:

$claude mcp add --transport http rivtor https://api.rivtor.com/mcp --header "Authorization: Bearer rvt_..."

Or the local server, so Claude Code uploads the folder it is working in:

$claude mcp add rivtor -e RIVTOR_TOKEN=rvt_... -- npx -y rivtor mcp

If you have already run npx rivtor login, leave out the -e RIVTOR_TOKEN=... part:

$claude mcp add rivtor -- npx -y rivtor mcp

Check it with claude mcp list, then ask Claude to deploy the current project.

Cursor

Add Rivtor to ~/.cursor/mcp.json for every workspace, or to .cursor/mcp.json in one project. Do not commit a file that contains your token.

~/.cursor/mcp.json

{
  "mcpServers": {
    "rivtor": {
      "url": "https://api.rivtor.com/mcp",
      "headers": {
        "Authorization": "Bearer rvt_..."
      }
    }
  }
}

Codex

Add the local server to ~/.codex/config.toml. Codex then uploads the folder it is working in.

~/.codex/config.toml

[mcp_servers.rivtor]
command = "npx"
args = ["-y", "rivtor", "mcp"]
env = { RIVTOR_TOKEN = "rvt_..." }

Any MCP client

Clients that read the common mcpServers format (Windsurf, Zed, Cline, your own agent) can run the local server like this:

mcp config

{
  "mcpServers": {
    "rivtor": {
      "command": "npx",
      "args": ["-y", "rivtor", "mcp"],
      "env": { "RIVTOR_TOKEN": "rvt_..." }
    }
  }
}

Clients that support Streamable HTTP can point at https://api.rivtor.com/mcp with the bearer header instead.

The local server on its own

$npx -y rivtor mcp

It speaks MCP over stdio and reads the token from RIVTOR_TOKEN, or from ~/.config/rivtor/config.json if you have run npx rivtor login. RIVTOR_API_URL changes the API endpoint and RIVTOR_CONFIG_DIR keeps the config somewhere else. Paths given to its deploy tool are absolute or relative to the directory the server was started in.

What your agent will see

Every tool returns JSON text: a DeployResult, a status object or a structured error.
Secret values are never echoed back, not even by the tool that set them.
The remote server also sends instructions with the typical loop: deploy, read error.cause and error.fix, fix, deploy again; ask once for missing secrets and call env_set.
When a plan limit matters (an app getting real traffic while it sleeps on Free, a second custom domain), one short upgrade note is attached to the response. At most once per session per trigger, and it never blocks a deploy.

Treat a token like a password. If one leaks, revoke it at /dashboard/tokens and create a new one; revoked tokens stop working immediately.