# Remote MCP server

> Server URL, access filters, tools, and behavior worth knowing

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/reference/mcp

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](https://nevia.cloud/docs/get-started/mcp.md).

## 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](https://nevia.cloud/docs/reference/workspace-permissions.md) 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](https://nevia.cloud/docs/reference/workspace-permissions.md). 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](https://nevia.cloud/docs/reference/computer-env.md) 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](https://nevia.cloud/docs/computers/checkpoints.md).

### 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](https://nevia.cloud/docs/reference/database-lifecycle.md).

## 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](https://nevia.cloud/docs/reference/operations.md).

## 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.