The remote MCP server runs at https://api.nevia.cloud/mcp over Streamable HTTP. Your MCP client signs you in with OAuth. For setup, see the Quickstart with MCP.
Access filters
Query parameters on the server URL narrow the tool list.
| Parameter | Effect |
|---|---|
readonly=true | Keeps only the tools marked read-only below. |
category= | Keeps one category. Repeat to select several: workspaces, secrets, computers, checkpoints, databases. |
workspace=<id> | Scopes calls to one workspace. Its ID becomes the default for workspace inputs. Other IDs are refused. |
Filters combine and never widen the credential's access. whoami, get_operation, and list_operations survive every filter. A workspace filter hides list_workspaces and create_workspace. Read-only also excludes get_database_connection, which returns a write credential. The API checks permissions on every call.
Tools
Identity and operations
| Tool | Purpose | Read-only |
|---|---|---|
whoami | Your principal, workspaces, and active restrictions | Yes |
get_operation | Read an operation, optionally waiting on it | Yes |
list_operations | List a workspace's operations | Yes |
Workspaces and access
| Tool | Purpose | Read-only |
|---|---|---|
list_workspaces | List your workspaces | Yes |
create_workspace | Create a workspace. You become its admin. | No |
get_workspace | Read a workspace | Yes |
update_workspace | Rename a workspace | No |
delete_workspace | Delete a workspace | No |
inspect_workspace_access | Show members and invitations, or look up one email | Yes |
grant_workspace_access | Add members or send invitations, up to 20 per call | No |
remove_workspace_access | Remove a member or revoke an invitation | No |
Deletion is refused while the workspace has computers or databases. Removing or demoting the last admin is refused. See Workspace permissions. After an unknown grant result, check with inspect_workspace_access before retrying.
Secrets and variables
| Tool | Purpose | Read-only |
|---|---|---|
list_secrets | List secret metadata | Yes |
get_secret | Read secret metadata | Yes |
list_variables | List variables | Yes |
get_variable | Read a variable, with its value | Yes |
MCP only reads. Create, update, and delete with nevia secrets, nevia variables, or the Console. No tool returns a secret's value. Variables are plain text that every member can read.
Computers
| Tool | Purpose | Read-only |
|---|---|---|
list_computers | List computers in a workspace | Yes |
list_images | List images and the default | Yes |
get_computer | Read a computer, with its env var names | Yes |
create_computer | Create a computer | No |
update_computer | Update name, protection, ports, or env | No |
delete_computer | Delete a computer | No |
branch_computer | Branch a computer | No |
sleep_computer | Put a computer to sleep | No |
wake_computer | Wake a computer | No |
exec_computer | Run a command and return its output | No |
Env entries accept secrets.NAME, variables.NAME, and {{secrets.NAME}} templates, for example DB_URI=postgres://app:{{secrets.DB_PASSWORD}}@db:5432/app. See Computer environment for the rules and limits.
exec_computer buffers output and keeps the first 64 KiB per stream. A nonzero exit code is a result, not a tool error. Never run a command that prints a secret, because its output comes back as is.
Computer checkpoints
| Tool | Purpose | Read-only |
|---|---|---|
list_computer_checkpoints | List a computer's checkpoints | Yes |
get_computer_checkpoint | Read a checkpoint | Yes |
create_computer_checkpoint | Create a checkpoint | No |
delete_computer_checkpoint | Delete a checkpoint | No |
restore_computer_checkpoint | Restore a checkpoint as a new computer | No |
See Create and restore checkpoints.
Databases
| Tool | Purpose | Read-only |
|---|---|---|
list_databases | List databases in a workspace | Yes |
get_database | Read a database | Yes |
create_database | Create a Postgres database | No |
update_database | Update name or protection | No |
delete_database | Delete a database | No |
get_database_connection | Read connection credentials | No |
reset_database_password | Set a new password | No |
branch_database | Branch a database | No |
sleep_database | Put a database to sleep | No |
wake_database | Wake a database | No |
A fresh branch's credentials can lag a few seconds behind ready. If connection is missing, call get_database_connection. See Database lifecycle states.
Waiting
Tools that create, branch, delete, or restore wait within the 45 s call budget. Pass wait: false to skip the wait.
| Outcome | Meaning |
|---|---|
completed | Finished, or nothing to wait for. |
accepted | Not confirmed complete. Follow next_steps, or continue with get_operation (wait_seconds up to 60). |
| Tool error | The request failed, or the awaited operation failed. |
Create and branch calls get a fresh idempotency key each time, so repeating one can create a second resource. Keep the operation ID and wait on it with get_operation.
Sleep and wake can return accepted with no operation yet. Read the resource again and do not repeat the transition.
See Operations and idempotency.
Errors and safety
Failures set isError: true and include code, message, status, details, and request_id. Delete, access removal, and exec carry destructive hints. The server does not enforce confirmation, so agents should confirm first.