MCP tool reference

What it's for

The complete list of what an AI agent connected to DADA Cloud can actually do: every tool the MCP server exposes, what each one takes, whether it changes anything, and what it returns. Use it when you want to know if a task is possible before you ask an agent to try, or when you are writing your own client against the server.

Setup lives in Control DADA Cloud from an AI agent (MCP). Worked end-to-end flows live in MCP recipes.

The surface: 41 tools

The server is generated by reflection over the platform's own REST API and then cut down by an allowlist, so a tool exists here only if it was deliberately chosen. That is why the number is 41 and not the 216 operations the API has. Anything not on this page is not reachable from an agent — the last section explains what was left out and why.

Two flags come from the protocol itself and your client may show them:

• read-only — the tool cannot change anything. All 20 list* / get* tools are read-only.
• destructive — the tool removes something. Exactly two are: deleteBox and deleteEnvVar. Well-behaved clients ask you before running these.

Every other tool is a create or an update: additive, and (except extendBox) asynchronous.

How arguments work

All tools take one flat object. There are no nested paths, no request bodies to assemble — you pass projectId, name, image and so on at the top level and the server routes each one into the URL, the query string or the body.

Three argument names carry almost every call:

projectId and envId are UUIDs even though the console shows you names. An agent that guesses "my-project" gets a 404. Start every session with listProjects → getProject.

Async: what "Committed" means

Most mutations return HTTP 202 and an operation id rather than a finished result. The tool result says so explicitly, and the flow is always the same:

1. Call the mutation. It returns an operation id.
2. Poll getOperation until the status is terminal — Committed or Failed.
3. Committed does not mean running. It means the desired state was written. Poll listApps until the app's phase is Healthy to know it actually came up.

If the phase never reaches Healthy, searchLogs is the next call.

extendBox is the only synchronous mutation (it moves a timestamp). boxUp is also synchronous but for the opposite reason: it holds the request open until a command has actually run inside the box.

Projects and environments

Apps

An app is a container workload: an image plus a port. Everything else the platform assembles.

There is no deleteApp and no restartApp. Both omissions are deliberate: delete is destructive enough to belong in the console with a human in front of it, and restart is unnecessary because env and image changes reconcile on their own.

Environment variables

Changes reconcile without a restart. There is no bulk-set tool on the agent surface — one key per call, which keeps a partial failure legible.

Databases

Git repositories and builds

The path from a repository to a running app.

Domains

Attaching a verified hostname to a specific app is not on the agent surface — finish that step in the console. See Custom domains and HTTPS.

Logs

Operations

App servers (VMs)

Boxes

A box is an ephemeral sandbox with root inside it — the shape an agent actually wants to work in. It owns exactly one environment, which is what every later attachment and hostname hangs off, and which crystallization promotes in place.

Getting a box

ssh_public_key is the public half. The platform never holds your private key, which is why there is nothing to leak on our side.

ttl_seconds is when the box goes to sleep, not when it is destroyed. spend_cap_rub, when reached, suspends the box — deliberately: a runaway should cost the customer money, never their data.

Living with a box

Making a box useful

What is deliberately not exposed

Knowing what an agent cannot do is as useful as knowing what it can.

• No command execution inside a box, ever. There is no boxExec and there will not be one. Our MCP surface is control plane only. The box hands out its own local MCP endpoint, which you add to your client as a second server — so your code and your model credentials never traverse our API. A command tool here would route every keystroke of your work through us, which is the opposite of the promise.
• No deleteApp, deleteDatabase, deleteProject, deleteAppServer. Deleting a customer's deployment is not an agent's job. deleteBox is the exception because ending a disposable body is the normal end of its life, and an agent that cannot release a box it created leaks paid capacity you pay for.
• No account or billing tools beyond getBoxUsage. An agent needs to see what it has spent, not your whole account.
• No admin, monitoring-config, model-serving, DNS-record or file-manager tools. They exist in the REST API; they are noise in a tool list an agent carries in its context on every turn.
• No bulk env-var set and no revealEnvVar. One key per call, and secret values stay unreadable.

Everything omitted here is still available over the REST API with the same token, so nothing is locked away — it is just not in the agent's hands by default.

Self-hosting the full surface

The allowlist is a file. Mounting your own at MCP_OVERRIDES_PATH with an empty keep list exposes every operation the API has. That is supported for private deployments and not something we do on the hosted platform, for the reasons above.