# servers operations

MCP tools and operation permissions for servers.

Generated from the shared operation catalog. Use [the JSON catalog](https://bytesmap.com/docs/reference/operations.json) for complete input schemas. Required dependency checks can be stricter than the resource permission listed below.

## server_cloud_capabilities

Read managed server connection readiness, acquisition availability, default resources and any unavailability reason for this workspace. Does not provision a server or reveal cloud credentials.

- **HTTP:** `GET /api/servers/cloud/capabilities`
- **SDK:** `client.servers.cloudCapabilities(input)`
- **Access:** workspace; server / read
- **Effect annotation:** Read-only

See the JSON schema for this input contract.

## server_cloud_owned

List managed cloud servers owned by the connected account and available to link into BytesMap. Does not create, modify or purchase infrastructure.

- **HTTP:** `GET /api/servers/cloud/owned`
- **SDK:** `client.servers.cloudOwned(input)`
- **Access:** workspace; server / read
- **Effect annotation:** Read-only

See the JSON schema for this input contract.

## server_cloud_acquire

Explicitly acquire a managed cloud server with a name and idempotencyKey. May provision paid infrastructure and requires workspace billing Admin. Use server_cloud_capabilities first; existing account and provisioning checks remain in force.

- **HTTP:** `POST /api/servers/cloud/acquire`
- **SDK:** `client.servers.cloudAcquire(input)`
- **Access:** workspace; billing / admin
- **Effect annotation:** May change state or run effects; destructive operation

| Input | Requirement | Description |
| --- | --- | --- |
| `name` | Required | string |
| `idempotencyKey` | Required | string |

## server_cloud_link

Link an existing owned managed cloud server into this workspace. Use server_cloud_owned to select it. Reuses its managed connection without exposing credentials or provisioning another server.

- **HTTP:** `POST /api/servers/cloud/link`
- **SDK:** `client.servers.cloudLink(input)`
- **Access:** workspace; server / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `remoteServerId` | Required | string |

## server_list

List saved servers that this user can access. Returns connection metadata and source counts, never SSH credentials.

- **HTTP:** `GET /api/servers`
- **SDK:** `client.servers.list(input)`
- **Access:** workspace; server / read
- **Effect annotation:** Read-only

See the JSON schema for this input contract.

## server_read

Read a saved server and its connection status under the current workspace permissions. Does not return credentials or open an arbitrary shell.

- **HTTP:** `GET /api/servers/:id`
- **SDK:** `client.servers.get(input)`
- **Access:** workspace; server / read
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `id` | Required | string |