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: 61 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 61 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 25 list* / get* tools are read-only.
• destructive — the tool removes something. Exactly four are: deleteBox, deleteEnvVar, deleteAgent and deleteServiceCache. 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:

You do not have to use UUIDs

Every tool that takes projectId, envId or appName also accepts names, and the server resolves them before the call runs:

{ "project": "internal", "env": "prod", "app": "telemost-bot", "key": "PGHOST", "value": "..." }

or, the same thing as one address:

{ "ref": "internal/prod/telemost-bot", "key": "PGHOST", "value": "..." }

If the project has exactly one environment, env may be left out. Names are resolved under your own permissions — nothing becomes reachable that was not already. An ambiguous project name (the same name visible to you in two orgs) comes back as a 409 that lists the candidates rather than a guess.

This is the whole point: one write is one call. The old listProjects → getProject → listApps → write walk is no longer needed, and listApps in particular used to return the console's full snapshot of every app in the environment — enough, on a busy project, to fill an agent's context window before the actual work began.

Every response that carries an id now carries the matching project / env / name beside it, so there is no return trip to turn an id back into an address.

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.

Addressing

resolveRef is the cheapest way into a session, and the only tool that shows the two env pictures side by side — see the warning under Environment variables.

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

An empty env_vars does not mean an empty app. An app assembled by hand in git has no rows in the console's table while its pods carry a dozen variables; reading env_vars: [] as "nothing here, safe to write" is how configuration gets erased. Check cluster_env, and check cluster_env.observed before believing an empty cluster list — observed: false means the platform could not look, not that there is nothing there.

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.

Writing an env var re-renders the app's values.yaml from the console's database. Anything hand-written in git that the console does not model would be dropped by that render, so the deploy is refused instead: the error names the exact paths at risk (common.extraEnv.PGHOST, common.servicePort, …). Import those keys into the console, or edit values.yaml directly, and retry.

Ask before you write: dry_run

Both writes accept dry_run: true. Nothing is saved and nothing is committed; the call returns 202 with an operation_id, and the operation's validation_result holds the plan for the values.yaml the write would produce:

{
  "dry_run": true,
  "values_path": "apps/internal/prod/telemost-bot/values.yaml",
  "added": ["common.extraEnv.NEW_KEY"],
  "changed": ["common.servicePort"],
  "removed": ["common.extraEnv.PGHOST", "common.useDotEnv"],
  "would_block": ["common.extraEnv.PGHOST", "common.useDotEnv"],
  "verdict": "THE REAL DEPLOY WOULD BE REFUSED: it deletes configuration that exists only in git (…)"
}

Read it with getOperation. removed is the list to look at first, and would_block is the subset that makes the real write fail. added includes the key you are about to set, so the plan describes the write you are considering rather than the state before it — values never travel, only key names.

Databases

Managed Redis

A scoped ACL user on the platform's shared Redis instance — the Redis analogue of a Postgres database, not a Redis server of your own.

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

Agents

A ManagedAgent is a kagent runtime the console renders as a Crossplane claim: name, system prompt, model, and which MCP servers it can call. Writing one goes through git, exactly like an app — saveAgent queues the commit, Argo applies it, and the cluster answers minutes later, not synchronously.

Access grants

An agent authenticates as its own /agents-group machine identity, which owns nothing by default. A grant is how that identity gets scoped access to one of your projects.

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.
• No agentChat* or agent/git/* tools. They exist in the REST API but back the console's own built-in ops assistant (the admin auto-fix button) and its git access — not the ManagedAgent runtime saveAgent writes. Wiring them in here would hand a tenant's agent the platform's own git-write credentials.

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.