Tool reference
Every tool /mcp offers, with what each one takes — generated from the daemon.
Every tool an agent finds at /mcp, grouped the way the daemon
registers them. A tool answers as the API key that called it: a member's
key deploys and reads, an admin's also configures the instance. What a
tool needs is in its inputs; what it refuses to do is in MCP.
Account
create_api_key
Issue an additional, independent API key for yourself under a given name (e.g. "mcp", "laptop") — it coexists with every key you already hold. role narrows the key to an access role from list_roles; without one it carries everything you may. A key can never create one that reaches more than it does.
| Input | Type | What it is |
|---|---|---|
name * | string | a label to recognize this key by later, e.g. "mcp" or "laptop" |
role | string | the name of an access role narrowing the key, from list_roles; omitted is everything the key calling this reaches |
* required
list_api_keys
List metadata for every API key you hold (id, name, timestamps). Key values are never shown again after creation.
Takes no input.
list_roles
List the access roles on this instance: each one's name and grants — for every kind of resource, a level (none, view or manage), whether it reads secrets, and which items (null for every one). A role narrows what a member or an API key reaches.
Takes no input.
revoke_api_key
Revoke one of your own API keys by id. Never refused, including your last one: a key that has leaked has to be able to go now, and being made to mint a replacement first would keep the leaked one live for as long as that took.
So what it costs is yours to weigh before calling it. Revoking the key this session is authenticating with stops this session at once — the next call fails. Revoking the last one leaves the account with no key at all, and whether that leaves a way in depends on whether it has a password, which this surface does not tell you.
| Input | Type | What it is |
|---|---|---|
id * | integer | the key's id, from list_api_keys |
* required
rotate_my_api_key
Replace the API key this MCP session is currently using with a freshly generated one. WARNING: the key authenticating this very session stops working immediately — this session's next call will fail. Every other key you hold is unaffected.
Takes no input.
whoami
Report who the API key this MCP session is using belongs to: the username, and the role it holds on this instance — admin or member.
Takes no input.
Projects and environments
create_environment
Create an additional environment within a project. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
project * | string | project slug |
slug * | string | short identifier used in URLs and as the environment name apps request. Permanent - it cannot be changed later |
* required
create_project
Create a project. Comes with a "production" environment, which can never be deleted. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
slug * | string | short identifier used in URLs: lowercase letters, digits and dashes. Permanent - it cannot be changed later |
* required
delete_environment
Delete an environment and every app deployed in it. Refused for the "production" environment, which every project must keep. Requires the admin role, and cannot be undone.
| Input | Type | What it is |
|---|---|---|
environment * | string | environment slug |
project * | string | project slug |
* required
delete_project
Delete a project, the environments inside it and every app in those — each app's container is stopped and removed first. Requires the admin role, and cannot be undone.
| Input | Type | What it is |
|---|---|---|
project * | string | project slug |
* required
get_environment_env
Read the environment variables set on one environment, plus the effective set an app there inherits (the project's, overridden by this environment's) with the source of every value.
| Input | Type | What it is |
|---|---|---|
environment * | string | environment slug |
project * | string | project slug |
* required
get_project_env
Read the environment variables set on a project. Every environment and every app below inherits them.
| Input | Type | What it is |
|---|---|---|
project * | string | project slug |
* required
list_environments
List the environments in a project.
| Input | Type | What it is |
|---|---|---|
project * | string | project slug |
* required
list_projects
List the projects on this instance.
Takes no input.
set_environment_env
Add, change or remove environment variables shared by every app in one environment. Only the keys you name are touched. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
environment * | string | environment slug |
project * | string | project slug |
set | object | variables to add or overwrite |
unset | array | names of variables to remove |
* required
set_project_env
Add, change or remove environment variables shared by every environment (and every app) in a project. Only the keys you name are touched. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
project * | string | project slug |
set | object | variables to add or overwrite |
unset | array | names of variables to remove |
* required
Apps
add_app_domain
Give an app another name to answer at over HTTP, and the port inside its container that name reaches. Point the name's DNS at this instance yourself; the certificate is issued on the first request that arrives. The name starts being served on the app's next deploy. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
host * | string | the name, e.g. api.example.com |
port * | integer | the port inside the container this name reaches. Omit for 8080 |
* required
add_app_volume
Give an app a volume: a directory at path inside its container whose contents survive deploys and restarts. It is mounted from the app's next deploy, so deploy it afterwards. An app with a volume runs as one copy on one machine — adding one is refused while the app is spread, scaled past one copy or autoscaled — and each deploy stops the old container before the new one starts, so the app is briefly unavailable. Removing a volume is not a tool: deleting data stays with a person. Requires the member role.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
path * | string | absolute path inside the container, e.g. /var/lib/rabbitmq. Not /, and not under /proc, /sys or /dev |
* required
cancel_app_deployment
Cancel an unfinished deployment before its swap, preserving the currently serving version.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference |
deployment_id * | integer | deployment id |
* required
create_app
Register a new app in a project and get its registry push path. environment defaults to "production" when omitted. Requires the member role.
| Input | Type | What it is |
|---|---|---|
build_args | object | Dockerfile build arguments; values are write-only and may persist in image history |
dockerfile | string | for a dockerfile app only, the recipe's path within the repository. Defaults to "Dockerfile" at the root. |
environment | string | environment slug (default "production") |
ignore_paths | array | exclude globs applied after watch paths |
image | string | for an external app, the image it pulls, without a tag — e.g. "registry.digitalocean.com/acme/api". Leave empty otherwise. |
name * | string | app name: lowercase letters, digits and dashes — becomes part of its registry image path. Permanent |
predeploy_command | string or array | shell string or argv array to run from the new image before swapping; empty string, empty array or null disables it |
predeploy_timeout | integer | pre-deploy timeout in seconds, up to 3600 |
project * | string | project slug |
ref | string | for a building app, the branch, tag or commit to build. Defaults to the repository's default branch. |
repo | string | for a building app, the https:// Git repository to build from. Leave empty otherwise. |
source | string | where the image comes from: "registry" (the default) for an image you push to Cubeship, "external" for one in a registry Cubeship does not run, "dockerfile" to build a Dockerfile from a Git repository, or "railpack" to build from a Git repository with no Dockerfile. Building requires the admin role. |
stop_grace_period | integer | container stop grace period in seconds, 0 to 3600 |
stop_signal | string | container stop signal, for example SIGTERM |
tag | string | the tag to run. Leave empty to follow the registry: on this instance's own that means a push deploys the app, and on any other it means latest. A building app has no tag — it names a ref. |
watch_paths | array | include globs; empty preserves deploy-on-every-push |
* required
delete_app
Delete an app and stop the container serving it. Images already pushed stay in the registry. This cannot be undone. Requires the member role.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
* required
deploy_app
Manually redeploy an app from an image tag already pushed to its registry path (no tag redeploys the tag it is already running, or the stored ref for a source that builds). Waits for the deploy to finish and reports the outcome; if this call times out first, the deploy carries on regardless — check it with get_app_deployments. Requires the member role.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
tag | string | image tag already pushed to the app's registry path (default "latest") |
* required
get_app
Get one app by reference: its domain, registry push path, status, and which project and environment it lives in.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
* required
get_app_deployments
List an app's recent deploys, newest first: whether each succeeded, and why it failed if it did. A deploy runs detached from the call that started it, so this is how you find out how one ended.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
* required
get_app_env
Read an app's environment variables: the ones set on the app itself, and the effective set its container runs with (project, then environment, then app — each overriding the last), with the source of every value. Read this before changing anything.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
* required
get_app_logs
Get an app's recent container log output (stdout and stderr combined).
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
server | string | which server's copy to read, for an app that runs on more than one; defaults to the one serving its names |
tail | string | number of trailing lines to return, e.g. "500", or "all" for the full log (default "200") |
* required
list_app_domains
List the names an app answers at over HTTP, each with the port inside the container it reaches. Read this before changing one: a name pointing at a port nothing listens on is what a 502 from a healthy container looks like.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
* required
list_app_tcp_ports
List an app's published TCP ports: each port its container listens on and the host port of the control plane it is published on, for protocols that are not HTTP, such as SSH. Publishing one is not a tool.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
* required
list_app_volumes
List an app's volumes: directories mounted into its container that outlive it, each with the path the container sees and the machine its data is on.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
* required
list_apps
List every app you can see, on this instance.
Takes no input.
remove_app_domain
Take a name off an app. The app goes on answering there until it is next deployed, which is when the proxy is told. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
host * | string | the name, e.g. api.example.com |
* required
set_app_domain_port
Change which port inside the container one of an app's names reaches — the fix when the proxy answers 502 but the container is healthy, because the app listens somewhere other than where the name points. The name keeps its certificate. It takes effect on the app's next deploy. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
host * | string | the name, e.g. api.example.com |
port * | integer | the port inside the container this name reaches. Omit for 8080 |
* required
set_app_env
Add, change or remove an app's own environment variables. Only the keys you name are touched — variables you don't mention are left alone. These are layered on top of (and override) the app's environment's and project's variables. Requires the member role.
| Input | Type | What it is |
|---|---|---|
app * | string | app reference: project/environment/app, or project/app for production |
set | object | variables to add or overwrite |
unset | array | names of variables to remove |
* required
update_app
Reconfigure an app: where its image comes from. Its domains are added and removed one at a time — an app can answer at several, each with its own port — so they are not here. A field you leave out is left as it was. The source and its settings travel together — naming a source without what it needs, or settings the source would ignore, is refused. Moving an app to a source that builds requires the admin role. The app's name cannot be changed.
| Input | Type | What it is |
|---|---|---|
build_args | object | Dockerfile build arguments; values are write-only |
dockerfile | string | for a dockerfile app only, the recipe's path within the repository |
health_path | string | the path Traefik asks this app for before trusting a container with traffic, e.g. /healthz. Send empty to check nothing, which is the default; a path that the app does not answer 2xx or 3xx on takes every replica out of rotation |
ignore_paths | array | exclude globs applied after watch paths |
image | string | for an external app, the image it pulls, without a tag |
predeploy_command | string or array | shell string or argv array to run from the new image before swapping it in; omit to preserve, empty string, empty array or null to clear |
predeploy_timeout | integer | pre-deploy timeout in seconds, up to 3600 |
ref | string | for a building app, the branch, tag or commit to build |
reference * | string | the app's reference: project/environment/name |
repo | string | for a building app, the https:// Git repository to build from |
source | string | registry, external, dockerfile or railpack. Send the settings the new source needs alongside it |
stop_grace_period | integer | container stop grace period in seconds, 0 to 3600 |
stop_signal | string | container stop signal, for example SIGTERM |
tag | string | the tag to run; send empty to follow the registry, which on this instance's own means a push deploys the app |
watch_paths | array | include globs; empty preserves deploy-on-every-push |
* required
Databases
add_datastore_extensions
Install Postgres extensions on a database that already exists — "pgvector", "vectorchord". Adds only: everything the database already has stays, and removing one is refused because the data may already depend on it. The container is replaced to pick the new image up, so the database is unreachable for a few seconds and comes back as "provisioning"; its data survives, being a host bind mount. Asking for what is already there does nothing. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
datastore * | string | the database's name on this instance |
extensions * | array | the extensions to install, by name: "pgvector", "vectorchord". "vectorchord" brings "pgvector" with it. Call list_datastore_engines for which versions offer which |
* required
attach_datastore
Wire an app to a database: the app's container is given DATABASE_URL and its parts — REDIS_URL for a Redis, MONGO_URL for a MongoDB — from its next deploy onwards. The app is named by its full reference, project/environment/name, and may be in any project. Use a prefix like "ANALYTICS_" when one app needs a second database of the same kind; a cache beside a database needs none, since the two name different variables. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
app * | string | the app's full reference: project/environment/name, or project/name for production |
datastore * | string | the database's name on this instance |
prefix | string | what the injected variables are named under, e.g. "ANALYTICS_". Leave empty for DATABASE_URL, REDIS_URL or MONGO_URL — whichever this engine writes. Only needed when two attachments would name the same variables. Uppercase, ending in an underscore |
* required
create_datastore
Provision a managed database on this instance. It belongs to the instance, not to a project — one database can serve apps in several. It comes up with a generated password, which is never returned: attach an app to it and the app receives the connection string as environment variables. Extensions can also be added afterwards with add_datastore_extensions, and can never be removed. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
database | string | the database to create inside the server. Defaults to the name with dashes turned into underscores |
description | string | what this database is for, in a sentence |
engine * | string | which server to run: postgres, mysql or mariadb. Call list_datastore_engines for what this release offers |
extensions | array | Postgres extensions to create the database with, by name: "pgvector", "vectorchord". More can be added later with add_datastore_extensions, but none can ever be removed. "vectorchord" brings "pgvector" with it. Call list_datastore_engines for which versions offer which. Empty for every engine but postgres |
name * | string | the database's name, unique on the instance: lowercase letters, digits and dashes. It is the container's name and is permanent |
username | string | the login to create. Defaults to "cubeship". MySQL and MariaDB will not accept "root" |
version | string | a version this release offers for that engine. Defaults to the newest. Permanent — a major version cannot be changed under an existing data directory |
* required
delete_datastore
Delete a managed database, stop its container and remove its data from disk. This cannot be undone and there is no backup. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
datastore * | string | the database's name on this instance |
* required
detach_datastore
Unwire an app from a database. Its container keeps the variables it was created with until it is deployed again, so this is not how you cut an app off in a hurry. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
app * | string | the app's full reference: project/environment/name |
datastore * | string | the database's name on this instance |
* required
get_datastore
Get one managed database by reference: its engine, version, extensions, status, the address apps reach it at, and what each attached app receives. Passwords are not reported.
| Input | Type | What it is |
|---|---|---|
datastore * | string | the database's name on this instance |
* required
list_datastore_engines
List the database engines this Cubeship release can run, the versions it offers for each, and the Postgres extensions available at each version. Call this before create_datastore rather than guessing a version or an extension.
Takes no input.
list_datastores
List every managed database on this instance: which engine and version each runs, which Postgres extensions it was created with, whether it is up, and which apps are attached to it.
Takes no input.
Object storage
attach_object_store
Wire an app to a bucket: the app's container is given S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY and S3_PATH_STYLE from its next deploy onwards. The app is named by its full reference, project/environment/name, and may be in any project. Use a prefix like "BACKUPS_" when one app needs a second bucket, since two attachments would otherwise name the same variables. The keys are never reported here — the app receives them. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
app * | string | the app's full reference: project/environment/name, or project/name for production |
bucket * | string | which bucket in that store the app is pointed at |
prefix | string | what the injected variables are named under, e.g. "BACKUPS_". Leave empty for S3_ENDPOINT and its parts. Only needed when one app is attached to two buckets. Uppercase, ending in an underscore |
store * | string | the object store's name on this instance |
* required
detach_object_store
Unwire an app from a bucket. Its container keeps the variables it was created with until it is deployed again, so this is not how you cut an app off in a hurry — rotating the credential is. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
app * | string | the app's full reference: project/environment/name |
bucket * | string | which bucket to unwire it from |
store * | string | the object store's name on this instance |
* required
get_object_store
Get one object store by name: where it answers, which provider it is, and — for one this instance runs — whether it is up. Keys are never reported.
| Input | Type | What it is |
|---|---|---|
store * | string | the object store's name on this instance |
* required
list_buckets
List the buckets in one object store. Requires the admin role, like everything about a store's contents.
| Input | Type | What it is |
|---|---|---|
store * | string | the object store's name on this instance |
* required
list_object_stores
List the object storage this instance can reach: the SeaweedFS servers it runs and the S3 endpoints it holds keys for. Each carries the endpoint an app on this instance connects to, so this is how you find out where an app should write. Keys are never reported.
Takes no input.
list_objects
List one level of one bucket: the folders directly under a prefix and the files directly in it, with their sizes and when each was last written. Names and sizes only — no tool here reads what is in a file. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
bucket * | string | the bucket to look in |
cursor | string | continue a listing that reported one. Omit for the first page |
prefix | string | the folder to list, e.g. "backups/2026/". Empty for the root of the bucket |
store * | string | the object store's name on this instance |
* required
The machine
instance_containers
List what every container on this instance is using right now — apps, databases and managed object stores together — heaviest CPU first. Each carries the name that identifies it: an app's full project/environment/name reference, a database's or a store's name. The CPU convention here is the container one: 100 is one core, unlike instance_metrics, where 100 is the whole machine. This is what answers "what is eating this box" without opening every app in turn.
Takes no input.
instance_metrics
Read what the machine this Cubeship instance runs on has been doing: how much of its CPU is busy (100 is every core, unlike an app's series where 100 is one core), how much of its memory is spoken for, how full the disk everything is kept on is, and how fast bytes are moving over its own interfaces. Samples are 30 seconds apart and a day is kept. A measurement this daemon cannot take comes back under unavailable with the reason, rather than as a number that is wrong.
| Input | Type | What it is |
|---|---|---|
server | string | machine name from the server listing; omitted means control-plane, never a cluster sum |
window | string | how much of the past to cover: 1h, 6h or 24h. Defaults to 1h |
* required
Servers
list_servers
List the machines this Cubeship instance is made of: the control plane — the box it was installed on, which holds the database, the dashboard, the registry and the builder — and the workers connected to it. Each carries what it last reported: its cores, memory and disk, the newest load reading, and whether it is answering. A server that has never connected is "pending"; one that connected and stopped is "unreachable", which says nothing about why.
Takes no input.
Backups
back_up_volume
Back up one of an app's volumes now. The app is stopped while the copy is taken and started again afterwards, whether or not it worked. The backup runs detached: this returns its row with status taking, and list_volume_backups says how it ended. It goes to an S3 store linked from outside this instance — the one named, or the volume's schedule's; this machine's disk and a store this instance runs are refused. A volume on another server is copied by that server, straight to the bucket. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
bucket | string | the bucket in that store. Required with store |
reference * | string | the app's reference: project/environment/name |
store | string | the S3 store linked from outside this instance to send it to, by name. Empty uses the volume's schedule |
volume_id * | integer | the volume's id, from list_app_volumes |
* required
list_volume_backups
List the backups of one of an app's volumes, newest first: when each was taken, whether it succeeded, its size, and whether it left this machine. Get the volume's id from list_app_volumes. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
reference * | string | the app's reference: project/environment/name |
volume_id * | integer | the volume's id, from list_app_volumes |
* required
Audit
list_audit_events
Read the audit log, newest first: who changed what, through the dashboard, the API or MCP, and every refused attempt. Filter by user, via (dashboard, api, mcp), outcome (ok, refused, failed) or target (e.g. an app's reference). Pass the returned next as before for older events. Requires the admin role.
| Input | Type | What it is |
|---|---|---|
before | integer | an event id; only older events |
from | string | only events at or after this: RFC 3339, or YYYY-MM-DD for midnight UTC |
limit | integer | at most this many, up to 500; default 100 |
outcome | string | ok, refused or failed |
target | string | only events whose target contains this |
to | string | only events before this, in the same form |
user | string | only this username |
via | string | dashboard, api or mcp |
* required