MCP server

SdV Cloud exposes a Model Context Protocol (MCP) server so AI agents — Claude Desktop, Claude Code, or any other MCP-compatible client — can manage your projects, service containers, and deployments on your behalf.

The server is named SdV Cloud Deployments and operates on behalf of the authenticated user, within a single organization.

Connecting a client

The MCP server is reachable over HTTP at:

POST https://<your-console-domain>/mcp

Replace <your-console-domain> with the domain where your SdV Cloud console is hosted.

1. Generate an API token

1. In the console, go to Settings → API Tokens.
2. Give the token a name (e.g. Claude Desktop).
3. Select the organization the token should act within — a token is permanently scoped to the organization chosen here.
4. Select the abilities the token should be granted (see Abilities below).
5. Click Generate token and copy the plaintext value shown. It is only ever displayed once — if you lose it, revoke it and generate a new one.

2. Configure your MCP client

Configure your client to call the endpoint above over HTTP (or streamable HTTP), sending the token as a bearer token:

Authorization: Bearer <your-api-token>

For example, with curl:

curl https://<your-console-domain>/mcp \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Consult your client’s documentation for how it expects a remote HTTP MCP server with a bearer token to be configured (for example, Claude Code’s claude mcp add --transport http, or Claude Desktop’s custom connector settings).

Authentication & scoping

Access is authenticated with a personal access token, generated from Settings → API Tokens.

Every token is created with:

• One organization — encoded as an internal org:{organization_id} ability at creation time. All tool calls made with the token operate within that organization only, and this cannot be changed later. To act within a different organization, revoke the token and generate a new one scoped to it.
• One or more abilities, which gate which tools the token can call.

Abilities

Ability	Grants
projects.read	Call read-only project tools (list_projects, get_project)
projects.write	Call project-mutating tools (create_project, update_project)
service-containers.read	Call read-only service container tools (list_service_containers, get_service_container)
service-containers.write	Call service-container-mutating tools (create_service_container, update_service_container)
deployments.read	Call read-only deployment tools (list_deployments, get_deployment, get_deployment_logs)
deployments.write	Call deployment-mutating tools (start_deployment, cancel_deployment)

Calling a tool without the required ability returns an error from the tool rather than an HTTP-level failure.

Note

Requests are rate-limited to 60 per minute, per token.

Tools

Tools that return a project, service container, or deployment always include a console_url field linking back to the corresponding page in the SdV Cloud web console.

Tool	Ability	Description
list_projects	projects.read	List the projects in the currently authorized organization.
get_project	projects.read	Get details of a single project by id.
create_project	projects.write	Create a new project in the currently authorized organization.
update_project	projects.write	Update a project name and/or description.
list_service_containers	service-containers.read	List the service containers within a project.
get_service_container	service-containers.read	Get the configuration of a service container.
create_service_container	service-containers.write	Create a new service container within a project, from a GitLab repository URL.
update_service_container	service-containers.write	Update any part of a service container configuration.
start_deployment	deployments.write	Trigger a new deployment for a service container.
cancel_deployment	deployments.write	Cancel a deployment that is pending, building, or deploying.
list_deployments	deployments.read	List the most recent deployments for a service container.
get_deployment	deployments.read	Get the status and details of a single deployment.
get_deployment_logs	deployments.read	Read the persisted build/deploy logs for a deployment.

list_projects

List the projects in the currently authorized organization.

No parameters.

Returns an array of:

Field	Type	Description
id	string	UUID of the project
name	string	Project name
description	string | null	Project description
console_url	string	Link to the project in the SdV Cloud console

get_project

Get details of a single project by id.

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project

Returns id, name, description, console_url (same shape as list_projects items).

create_project

Create a new project in the currently authorized organization.

Parameter	Type	Required	Description
name	string	Yes	Project name (max 255 characters)
description	string	No	Project description (max 500 characters)

Returns the created project: id, name, description, console_url.

update_project

Update a project name and/or description.

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project
name	string	No	New project name
description	string	No	New project description

Returns the updated project: id, name, description, console_url.

list_service_containers

List the service containers within a project.

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project

Returns an array of:

Field	Type	Description
id	string	UUID of the service container
name	string	Service container name
container_type	string	One of http, worker, scheduled
is_configured	boolean	Whether the service container has completed initial configuration
console_url	string	Link to the service container in the SdV Cloud console

get_service_container

Get the configuration of a service container. Environment variable values are never returned — only their keys.

Parameter	Type	Required	Description
service_container_id	string	Yes	UUID of the service container

Returns:

Field	Type	Description
id	string	UUID of the service container
name	string	Service container name
container_type	string	One of http, worker, scheduled
branch_to_deploy	string	Git branch deployed
port	integer	Exposed port
memory_limit	integer	Memory limit in MB
cpu_limit	number	CPU limit in cores
environment_variable_keys	string[]	Names of configured environment variables — values are never returned
is_configured	boolean	Whether the service container has completed initial configuration
service_url	string | null	Public URL of the service, if applicable
console_url	string	Link to the service container in the SdV Cloud console

create_service_container

Create a new service container within a project, from a GitLab repository URL (e.g. https://gitlab.example.com/group/project). Only GitLab repositories are currently supported.

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project
name	string	Yes	Service container name
container_type	string	Yes	One of http, worker, scheduled
git_repository_url	string	Yes	URL of the GitLab repository to deploy, e.g. https://gitlab.example.com/group/project

Returns id, name, console_url.

The new service container is not immediately deployable — configure branch_to_deploy and port with update_service_container, then call start_deployment.

update_service_container

Update any part of a service container configuration: branch, port, resources, environment variables, storage volumes, autoscaling, hibernation schedules, IP allowlist, and basic auth. All parameters except service_container_id are optional and only replace what’s provided; environment variables, storage volumes, hibernation schedules, and the IP allowlist are each replaced wholesale when passed.

Parameter	Type	Required	Description
service_container_id	string	Yes	UUID of the service container
name	string	No	Service container name
branch_to_deploy	string	No	Git branch to deploy
build_mode	string	No	One of automatic, dockerfile
dockerfile_path	string	No	Path to the Dockerfile, relative to the repository root
port	integer	No	Exposed port (1-65535)
memory_limit	integer	No	Memory limit in MB (250-8000)
cpu_limit	number	No	CPU limit in cores (0.25-4)
environment_variables	array of {key, value}	No	Replaces all environment variables
storage_volumes	array of {mount_path, size, storage_class}	No	Replaces all storage volumes. size is in GB (1-100); storage_class is nfs
autoscaling_enabled	boolean	No	Enable CPU-based autoscaling
min_replicas	integer	No	Minimum replica count (1-10)
max_replicas	integer	No	Maximum replica count (1-10)
cpu_threshold	integer	No	CPU percentage that triggers scaling (10-90)
hibernation_enabled	boolean	No	Enable scheduled hibernation
hibernation_schedules	array of {days, start_time, end_time}	No	Replaces all hibernation schedules. days is an array of mon-sun; start_time/end_time are HH:MM (24-hour)
ip_allowlist_enabled	boolean	No	Restrict access to an IP allowlist
ip_allowlist	array of {ip, description}	No	Replaces the IP allowlist
basic_auth_enabled	boolean	No	Require HTTP basic auth
basic_auth_credentials	array of {username, password}	No	Replaces the basic auth credentials

Returns id, name, environment_variable_keys, console_url.

start_deployment

Trigger a new deployment for a service container.

Parameter	Type	Required	Description
service_container_id	string	Yes	UUID of the service container

Returns id, status, console_url. Fails if the service container isn’t fully configured yet, or already has a deployment in progress.

cancel_deployment

Cancel a deployment that is pending, building, or deploying.

Parameter	Type	Required	Description
deployment_id	string	Yes	UUID of the deployment

Returns id, status, console_url.

list_deployments

List the most recent deployments (up to 20) for a service container.

Parameter	Type	Required	Description
service_container_id	string	Yes	UUID of the service container

Returns an array of:

Field	Type	Description
id	string	UUID of the deployment
status	string	One of pending, building, deploying, succeeded, failed, cancelled
branch	string	Deployed git branch
triggered_via	string	One of web, cli, mcp, api
created_at	string	ISO 8601 creation timestamp
console_url	string	Link to the deployment in the SdV Cloud console

get_deployment

Get the status and details of a single deployment.

Parameter	Type	Required	Description
deployment_id	string	Yes	UUID of the deployment

Returns:

Field	Type	Description
id	string	UUID of the deployment
status	string	One of pending, building, deploying, succeeded, failed, cancelled
branch	string	Deployed git branch
commit_sha	string | null	Commit SHA that was deployed
error_message	string | null	Error message if the deployment failed
triggered_via	string	One of web, cli, mcp, api
created_at	string	ISO 8601 creation timestamp
finished_at	string | null	ISO 8601 completion timestamp
console_url	string	Link to the deployment in the SdV Cloud console

get_deployment_logs

Read the persisted build/deploy logs for a deployment. Logs are a point-in-time snapshot, not a live stream.

Parameter	Type	Required	Description
deployment_id	string	Yes	UUID of the deployment

Returns:

Field	Type	Description
logs	object	Log text keyed by deployment stage name
console_url	string	Link to the deployment in the SdV Cloud console

Prompts

Alongside its tools, the server exposes two guided prompts:

Prompt	Arguments	Description
deploy_new_service	git_repository_url (required), project_id, name, branch_to_deploy, port	Guides the assistant through onboarding and deploying a new service container from a GitLab repository.
diagnose_failed_deployment	deployment_id (required)	Guides the assistant through diagnosing why a deployment failed and proposing a fix.