Riven / MCP Server

MCP Server

Connect AI tools like Claude to your Riven account using the Model Context Protocol (MCP). Once connected, you can ask an AI assistant to check your deployments, manage services, and more — in plain English.

1Connect Claude Desktop

Open your Claude Desktop config file (Settings → Developer → Edit Config) and add the following:


{
  "mcpServers": {
    "riven-deploy": {
      "command": "npx",
      "args": [
        "-y",
        "@rivendeploy/mcp-server"
      ]
    }
  }
}

Restart Claude Desktop. The first time the assistant uses a tool, a browser window opens to sign in to Riven and approve the connection. There is no token to copy and no secret to store.

✓

You choose which workspace the connection can reach, and which permissions it gets, on the approval screen. You can revoke it later from MCP settings in your dashboard.

2Other clients

Claude Code

claude mcp add riven-deploy -- npx -y @rivendeploy/mcp-server

Cursor — add the same block as above to ~/.cursor/mcp.json.

VS Code

code --add-mcp '{"name":"riven-deploy","command":"npx","args":["-y","@rivendeploy/mcp-server"]}'

Connect by URL. Clients that speak Streamable HTTP and OAuth can skip the package entirely and add the hosted server directly:

https://api.rivendeploy.com/mcp/mcp

Sign-in, consent and token refresh are handled by the client. The server publishes its OAuth metadata at /.well-known/oauth-authorization-server and registers clients dynamically, so there is nothing to configure by hand.

3Available tools

Once connected, the assistant can call these on your behalf. Each needs the permission listed beside it.

Tool	What it does	Permission
`list_projects`	Every service in your workspace, with status and URL.	deploy:read
`get_service`	One service, looked up by id or by name.	deploy:read
`list_deployments`	Recent deployments for a service, newest first.	deploy:read
`whoami`	Which account and workspace the connection is using.	account:read or deploy:read
`start_service`	Start a stopped service.	deploy:write
`stop_service`	Stop a running service.	deploy:write or deploy:stop
`restart_service`	Restart in place, without rebuilding.	deploy:write or deploy:restart
`redeploy_service`	Build and deploy from the current source.	deploy:write

Deleting a service is deliberately not available to an assistant. Do that from the dashboard, where it takes a deliberate confirmation.

4Using a personal access token

For CI and scripts, where no browser is available to sign in, pass a Personal Access Token instead. Create one from the MCP section of your dashboard, then:


{
  "mcpServers": {
    "riven-deploy": {
      "command": "npx",
      "args": [
        "-y",
        "@rivendeploy/mcp-server"
      ],
      "env": {
        "RIVEN_TOKEN": "rnv_xxxxxxxxxxxxxxxxx"
      }
    }
  }
}

✓

Your token is displayed only once when created. If you lose it, revoke it from the dashboard and create a new one.

Give the token only the permissions it needs. A token with just deploy:read can answer questions about your services but cannot change what is running.

5Example prompts

Once connected, just ask in plain English:

Which of my Riven services are down?Redeploy the api service.Show me the last five deployments for web.

The assistant picks the right tool and replies with the result. Anything that changes what is running will say so before it acts.

6Troubleshooting

The sign-in window never opens. Run npx @rivendeploy/mcp-server --no-browser to print the URL and open it yourself.

"Port 33418 is already in use". Pass --callback-port with a free port.

A tool says the connection is missing a permission. Run npx @rivendeploy/mcp-server --logout and connect again, granting the permission this time.

Every tool call is logged. You can see what a connection has done, and when, from the MCP section of your dashboard.

Next steps

Riven CLI →

Manage your services from the terminal instead.

Authentication →

Create and manage your Personal Access Tokens.