Skip to main content
Glama
Constructor Research MCP

Constructor Research MCP

by NRGGIT

Constructor Research MCP

0.6.1: inside a Constructor desk, a key saved for your Constructor works even when the desk names another address for it (ROLOS_API_SERVER, e.g. constructor.app in a desk opened on acme.constructor.app).

0.6: a registry image the project does not have is added to it as an external image, with no desk and no build; Constructor refuses a bad one at once, with its reason.

0.5: one command sets it up: npx -y constructor-research-mcp@latest install finds your coding agents, saves your access key and adds the MCP to each of them.

0.4: works with Constructor's public API and a personal access key (rk-…); browser sign-in is gone. On a Constructor without the public API yet, pin the previous version: constructor-research-mcp@0.3.3.

Local stdio MCP for Codex CLI, Claude Code, OpenCode, jcode, Cline, Cursor and Gemini CLI. Submit the whole application once; the MCP builds images, connects services, configures them and starts them. The agent supplies missing configuration and reports the result.

Install

You need Node.js 22+ and your personal access key (rk-…); the MCP does not work without it. In a terminal, run:

npx -y constructor-research-mcp@latest install

It finds the coding agents on your machine (Claude Code, Codex, OpenCode, jcode, Cline, Cursor, Gemini CLI), asks which of them to set up and whether for this project or globally, and where you use Constructor Research (constructor.app or your organisation's instance). It then links to the page where you create an access key, takes the key hidden, checks it with Constructor and saves it to the key file below. Each agent gets an entry that runs npx -y constructor-research-mcp@latest and holds no key. Every settings file it changes is first copied to <file>.constructor-backup; --verbose shows the files and entries, --dry-run changes nothing, --help lists the options for scripted installs. Then restart the agents.

By hand

Add the MCP with the key; the address is https://constructor.app unless your organisation has its own Constructor (e.g. https://acme.constructor.app).

Claude Code

claude mcp add --scope user constructor-research \
  -e CONSTRUCTOR_BASE_URL=https://constructor.app \
  -e CONSTRUCTOR_ACCESS_KEY=rk-your-key \
  -- npx -y constructor-research-mcp@latest

Codex

codex mcp add constructor-research \
  --env CONSTRUCTOR_BASE_URL=https://constructor.app \
  --env CONSTRUCTOR_ACCESS_KEY=rk-your-key \
  -- npx -y constructor-research-mcp@latest

OpenCode: add the entry to ~/.config/opencode/opencode.json (layouts for 1.x and 2.x in INSTALL.md).

Then restart the tool and ask the agent anything about Constructor. Windows notes, the optional wake-up hooks and troubleshooting are in INSTALL.md. Restarting the tool picks up a new version.

The key then sits in the tool's settings file (~/.claude.json, ~/.codex/config.toml, opencode.json). To keep it out of there, add the MCP without the two variables and save the key with set-key (below).

Related MCP server: golive-mcp

Access key and connection

The MCP uses only a personal access key (rk-…) from Constructor's public API; there is no browser sign-in. Every request carries it as X-Research-AccessKey: Bearer rk-…, to the account API (/api/platform-account/v1), the desk storage (WebDAV) and the logs alike. The key never goes through the chat. It comes from the MCP settings (CONSTRUCTOR_ACCESS_KEY, with CONSTRUCTOR_BASE_URL, as in Install), or from a key file the user saves in a terminal, where the key is read hidden, checked against Constructor and saved:

npx -y -p constructor-research-mcp@latest constructor-research-set-key https://acme.constructor.app

It goes to ~/.config/constructor-research/access-key.json (mode 600) together with the Constructor it belongs to, and the MCP works with that Constructor. All harnesses (Claude Code, Codex, OpenCode) and the wait command share this one file. Every request rereads it, so a new key needs no restart. A key is never sent to a Constructor other than the one it was saved for.

CONSTRUCTOR_ACCESS_KEY in the MCP settings takes precedence over the file. The wait hooks do not see the MCP settings: with the key there, give the hooks the same two variables in their own environment, or save the key with set-key as well.

Without a key, or when Constructor rejects it (401: revoked, expired or for another Constructor), tools return needs_key with the command above; a deployment pauses as needs_key and resumes on the next check once a valid key is saved. A desk link from another Constructor returns wrong_environment.

Deployment must be switched on for the project. When it is off, the MCP switches it on (POST /projects/{id}/deployment), which only the project owner may do. For anyone else (error 40005), the operation fails at stage prepare with a message asking the project owner to switch it on in Constructor.

Variable

Default

CONSTRUCTOR_BASE_URL

unset: the Constructor of the saved key, else https://constructor.app; set, it fixes the host

CONSTRUCTOR_API_PATH

/api/platform-account/v1

CONSTRUCTOR_STORAGE_PATH

/api/platform-storage

CONSTRUCTOR_ACCESS_KEY

unset: the key file is used

CONSTRUCTOR_KEY_FILE

~/.config/constructor-research/access-key.json

CONSTRUCTOR_DESK_ROOT

~/project (inside a desk only)

CONSTRUCTOR_STATE_DIR

~/.local/state/constructor-research-mcp

CONSTRUCTOR_UPLOAD_SETTLE_SECONDS

30

CONSTRUCTOR_READINESS_SECONDS

60

HTTPS is required except on localhost.

Inside a Constructor desk (VS Code)

When the MCP runs in VS Code inside a Constructor Research desk, it finds that desk from the environment Constructor sets there (ROLOS_PROJECT_ID/RESEARCH_PROJECT_ID, ROLOS_DESK_ID/RESEARCH_DESK_ID, ROLOS_API_SERVER/RESEARCH_API_SERVER) and works in it:

  • the desk's project folder (~/project, or CONSTRUCTOR_DESK_ROOT) is its disk, so the agent creates and changes files there directly; nothing is uploaded, and sync_files, list_files, create_folder, move_path and delete_path answer local_desk for this desk;

  • build_image, deploy_app, update_app, start_app, stop_app and list_images act on this desk and project without a desk link; a desk_url or other IDs still name another desk;

  • build.dockerfile is the path inside the project folder (/backend/Dockerfile), or build.local_path names a folder inside it; Dockerfiles are checked from the local files;

  • two addresses can lead to the user's Constructor: the one the user named (the saved key's, or CONSTRUCTOR_BASE_URL; without either, the desk's server) and the desk's server (ROLOS_API_SERVER), which may differ from it, e.g. https://constructor.app in a desk opened on https://acme.constructor.app. The MCP asks the desk's server once whether it accepts the key: if it does, requests go there, else to the user's address. Links shown to the user and key help keep the user's address, and desk links from either address are accepted. Setup (install, constructor-research-set-key) checks the key with both and saves it for the user's address when either accepts it.

CONSTRUCTOR_LOCAL_DESK=0 turns this off.

Thirteen tools

Tool

Agent's task

deploy_app

Describe all services in one request, or resume that deployment with overrides.

update_app

Describe selected changes/additions; the MCP builds and restarts affected services.

start_app / stop_app

Request lifecycle changes for all or selected services.

get_deployment

Map all deployments, inspect a project or app, or wait for background execution.

get_logs

Last 10–50 lines of a build or service log (see "Logs").

build_image

Build an image independently when needed.

list_images

List image IDs, Dockerfiles and native build statuses.

list_files

List a disk's files and folders; recursive:true walks subfolders.

create_folder

Create a disk folder, including missing parents.

sync_files

Upload new and changed files; asks once before replacing existing files.

move_path

Rename or move files/folders in one batch, approved once; never overwrites.

delete_path

Delete files/folders in one batch; reports first, deletes only with confirm:true.

No special clone/new-instance workflow is implemented. The thirteen tools use the same standard MCP transport across harnesses.

The agent does not choose a project or desk. It asks the user for the desk link: open the desk in Constructor and copy the browser address, for example

https://constructor.app/research/projects/<project_id>/desks/<desk_id>/viewer/file

Every tool accepts it as desk_url, in place of project_id/desk_id. Anything after /desks/<desk_id> is ignored. The link's host must be the Constructor the key belongs to (inside a desk, the desk's server too); a link from another one returns wrong_environment (see the access key above). Explicit IDs, if also sent, must agree with the link. In deploy_app/update_app, builds without their own desk_id use the link's desk; start_app/stop_app and get_deployment take only the project from it.

Given only project_id, the MCP finds the desk itself:

  • one desk in the project: it is used;

  • no desk: deploy_app/update_app create one (<application>-source) for the sources; the file tools return an error;

  • several desks: nothing is changed and the tool returns desk_choice_required with each desk's name, id and desk_url. The agent asks the user which one and repeats the call with that link or ID.

Normal deployment flow

  1. Inspect with get_deployment: no arguments returns the map of all deployments (every deployment-enabled project → applications → services with names, native statuses, public URLs and ports; other projects are listed by name only); desk_url or project_id returns that project's disks, images, hardware and apps; add application_id for service details.

  2. If the app is built from source, pass build.local_path (the local folder with the Dockerfile) and deploy_app uploads it first, or upload separately with sync_files.

  3. Call deploy_app once with the entire application. Use build sources, existing image IDs, or a mix.

  4. The MCP executes the job in the background. It generates the deployment ID and resolves service references.

  5. If the response is still in progress, call get_deployment with that ID to wait for the result. Do not write loops to advance individual steps.

  6. On failure, report the stage/service and ask the user to check logs in Constructor. No browser or debugging detour, and no automatic fallback to an older image.

Every execution tool accepts wait_seconds from 0 to 20 (default 20). A response after that time is not a timeout/cancellation: execution continues while the MCP process is connected. get_deployment waits for completion or a user-action state; it does not drive the pipeline. wait_seconds:0 returns immediately.

The background executor runs inside the MCP process, not a detached daemon. Closing the harness stops local orchestration; remote builds continue. On the next MCP startup, unfinished checkpoints recover automatically. If a mutation's outcome is uncertain, recovery pauses instead of repeating it.

Whole-application example

{
  "project_id": "PROJECT_ID",
  "application_name": "subfinder",
  "files_uploaded": true,
  "services": [
    {
      "name": "backend",
      "build": { "desk_id": "DISK_ID", "dockerfile": "/backend/Dockerfile" },
      "ports": [{ "number": 8080, "expose_to_internet": true }]
    },
    {
      "name": "frontend",
      "build": { "desk_id": "DISK_ID", "dockerfile": "/frontend/Dockerfile" },
      "ports": [{ "number": 3000, "expose_to_internet": true }],
      "environment_variables": {
        "NUXT_PUBLIC_API_BASE_URL": {
          "service": "backend",
          "exposure": "public"
        }
      }
    }
  ]
}

No request ID is required. An optional request_id is a retry key (descriptive strings and legacy UUIDs are accepted); reusing it with the original request resumes the same operation. Save the returned deployment_id. After an interrupted initial call without a retry key, an undisclosed checkpoint may exist; inspect state/resources rather than blindly resubmitting.

Service references

Public URL, resolved after the target service is created:

{ "service": "backend", "exposure": "public" }

Internal host and port:

{ "service": "database", "port": 5432 }

Internal HTTP URL:

{ "service": "backend", "port": 8080, "scheme": "http" }

References imply dependency ordering. depends_on can add explicit ordering. Unknown targets, cycles and unconfigured target ports are rejected. Public references require a public target port and use HTTPS. Internal addresses follow svc-{name}.app-{project_id_first4}{application_id_first4}.svc.cluster.local:{port} for this environment. Public URLs use the API link or https://{service_id}.constructor.pro.

Private DNS works between containers; browser JavaScript needs a public backend URL or a frontend server proxy. Build-time frontend variables are not injected into image builds by this MCP: runtime wiring requires an application that reads runtime configuration.

Image reuse and limits

Replace a service's build with "image_id":"IMAGE_ID" to skip building, or with "image":"registry/repo:tag" to run a registry image unchanged, such as jgraph/drawio:latest from Docker Hub. Which of build, image and image_id fits is the agent's choice; the tool descriptions say what each one does. list_images returns compact records with source (desk_build or external), reference and build_status (not_started, snapshot_creation, in_progress, done or error); detailed:true returns full records.

With image, the MCP first looks for it in the project (by reference or name). External images there (source: external) are pulled, not built, so they are used whatever their build status, unless it is error. An image the project does not have is added to the project as an external image (POST /projects/{id}/images/external): no desk, no upload, no build. Constructor reads the image manifest at once and refuses a missing tag, a private image, an image without a linux/amd64 variant or a malformed reference; the MCP then returns image_refused with Constructor's reason and creates nothing else. Docker Hub references are sent in the short form (docker.io/library/nginx:1.27 becomes nginx:1.27), which Constructor requires for now. A reference without a tag means latest, which moves: the result then carries image_warnings. On a Constructor without this endpoint, the MCP falls back to building the image on the desk from a one-line FROM <image> Dockerfile in .constructor/images/<name>/.

  • Build storage is omitted by default, using the API's documented 50 GB default. Explicit ephemeral_build_disk_size_gb overrides must be 10–1000 GB.

  • Each service can have multiple ports (1–65535), with at most one public port. That port must match where the container listens.

  • Hardware: omit it. New services get the smallest available non-GPU option; existing services keep theirs. Only when the app needs more, pass minimums hardware: {cpu, ram_gb, gpu}; the MCP picks the smallest available option that meets them (GPU options only when gpu:true). get_deployment with desk_url lists hardware_options as plain specs (CPU, RAM, GPU), without names or IDs.

  • Up to three volumes, each 10–2000 GB, with a mount path.

  • Service names are lowercase DNS labels, max 63 characters.

Missing prerequisites

  • No or rejected key: needs_key with the command to save one (see Access key). Save a valid key, then check the same deployment again.

  • No project/disk: omit project_id, optionally supply project_name, and use build sources without disk IDs. MCP creates the project/disk and enables deployment tools.

  • Files absent: needs_upload lists disks and Dockerfile paths. Upload with sync_files (or manually), then call get_deployment with deployment_id and files_uploaded:true.

Before any build, the MCP reads each Dockerfile from its disk. A missing one returns dockerfile_missing and nothing is created. When every build's Dockerfile is present, the upload pause is skipped. The MCP also returns dockerfile_warnings (in message too) for: a name other than Dockerfile/<name>.dockerfile, no FROM, no EXPOSE or a service port that is not exposed, localhost/127.0.0.1 in ENV/ARG/CMD/ENTRYPOINT, a docker-compose file next to the Dockerfile, compose-style default hosts in ENV (http://cerbos:3592, temporal:7233), an ENTRYPOINT/CMD script copied from the build context with no chmod (files uploaded to a desk lose the executable bit, so such a container exits before printing anything), and listen [::] in an nginx .conf/.template the Dockerfile copies (nginx exits where the cluster has no IPv6). The same rules are in the tool descriptions, so agents see them before writing a Dockerfile. An existing project with a conflicting name requires an explicit ID; the MCP does not guess.

Resume with a replacement image

After the user selects a replacement, call the original tool (deploy_app or update_app) with the same deployment ID and only the service overrides:

{
  "deployment_id": "RETURNED_DEPLOYMENT_UUID",
  "services": [{ "name": "frontend", "image_id": "WORKING_IMAGE_ID" }]
}

Successful builds and unchanged service definitions are retained. Environment overrides merge with saved values. Supplying a new build source retries that service's build; the previous successful builds are reused. Overrides cannot add services that were not in the saved operation; use a new update for additions.

A failed build returns failure.stage, failure.service, failure.dockerfile and failure.image_id. A service API failure includes the stage and service. The message is concise: “Please check the logs in Constructor.” Logs and browser access are not part of this workflow.

  • An environment variable can be {service, port} instead of a string. The MCP turns it into the other service's internal address as a bare host:port (e.g. svc-temporal.app-1234abcd.svc.cluster.local:7233), which suits gRPC, databases and Temporal. Add scheme: "http" to get http://host:port. {service, exposure: "public"} gives the public https URL.

  • A volume belongs to one service and the container can write to it. Data lives as long as the service: it survives stop/start, restarts and image changes. It is wiped when the service is deleted, or when the volume is removed or its name, mount point or size changes. update_app therefore returns confirm_required with volumes_to_wipe before such a change; after the user approves, repeat with confirm_volume_wipe=true. Another service cannot mount it; a request that mounts the same volume on two services is rejected before anything changes. Share data over an internal link instead.

Updates and lifecycle

update_app takes project_id, application_id and selected services. Match an existing service by exact name, or supply service_id when renaming. New names add services and require an image or build. Services omitted from the request remain untouched.

Omitted image/hardware/ports/volumes are retained. Environment variables merge by name; deletion of environment variables is not implemented. Supplied port and volume lists replace those lists, preserving matching IDs by port number/volume name. Empty lists remove attachments; no volume-data migration occurs.

All required builds must succeed before existing services are changed. The MCP stops affected running services, sends a complete merged PATCH and starts them. Multiple services are handled internally, not through agent-managed start/stop loops. This is not an atomic rollout; a failure can leave some services updated. Avoid concurrent UI edits and finish one operation on an app before starting another.

start_app and stop_app take project_id, application_id and optional service_names. started/stopped mean requests accepted, not verified readiness/teardown. Native statuses (starting, running, stopping, stopped, failed) remain visible. A finished job's service status can be refreshed with get_deployment; the job's historical outcome is distinct from current native status. Readiness is always unverified.

Build and start reliability

Learned from live runs (28 Oct 2026):

  • Upload settle. A build started right after its Dockerfile was uploaded failed every time; with a pause it built first time. After any upload to a disk, builds on that disk wait until 30 s have passed (status preparing, message says so). CONSTRUCTOR_UPLOAD_SETTLE_SECONDS changes it; 0 disables.

  • Confirmed failure, one automatic rebuild. The platform briefly reports error and then in_progress again, so an error counts only when seen twice for the same image. The first confirmed failure is rebuilt once under a new image name, after re-uploading local_path sources and re-checking the Dockerfile on the disk. build_retried names the image that failed.

  • Actionable failure. A build that fails again returns failure.image_name, first_image_name, desk_link, and a message saying how to see the log: Constructor does not keep build logs, so rebuild that Dockerfile from the UI and watch it live.

  • Readiness check. After start, the MCP requests each public URL until it answers (any HTTP status below 500) or 60 s pass (status verifying). readiness is then http_ok, not_responding (with readiness_checks and a hint; services of the deployment that printed nothing since starting are named, with an ordered checklist: entrypoint not executable, wrong entrypoint path, nginx IPv6 listen, wrong listen address or port), or no_public_url. CONSTRUCTOR_READINESS_SECONDS changes the window; 0 disables.

State and recovery

Progress and sanitized results are checkpointed. Configuration secrets remain in owner-only local checkpoint files (0600, directory 0700); tool responses return environment-variable names, never values. The access key is not checkpointed. Do not commit credentials or state.

Checkpoints are bound to the API endpoint. A shared state directory coordinates local harnesses. resume:false on get_deployment observes without scheduling execution or confirming uploads; already running background work is not paused.

Terminal states: built, started, stopped, failed, needs_reconciliation, superseded. A new update_app, start_app or stop_app for an application ends that application's unfinished deployments as superseded, so an older one cannot apply its images after the newer one; its builds keep running on Constructor but are not used. The new result lists them in replaced, with the services they were changing that the new update leaves out. User-action pauses: needs_key, needs_upload. Other statuses indicate background progress. An executor stops after one hour rather than retrying forever.

For needs_reconciliation, inspect the possible remote mutation before submitting a new operation. The server never blindly repeats an uncertain create. A .lock left by a process that no longer exists (a server killed or restarted mid-step) is removed automatically on the next operation; a lock held by a live process returns busy. Checkpoints remain available. No rollback or resource deletion is automated.

Logs

Constructor serves logs only live, as a stream: a build log while the build runs, a service log for the service's current container. Each connection replays the log from the start, then streams. Nothing is kept afterwards: a finished build has no log, and a restarted container starts with an empty one, so a crash-looping service shows no log at all. The MCP therefore follows every build and service it starts and keeps only the last 50 lines of each, in memory and in logs/ in the state directory, so it stays small however long the log is.

  • A build is followed from its first status check until it ends; a dropped connection is reopened and replayed lines are skipped. When the stream closes, reopening it answers "not found" and the kept lines are final.

  • A service is followed from its start request, or from when get_deployment shows it running, for 15 minutes after anyone last asked for it.

  • Restarts: Constructor reports no restart count, so the MCP detects them in the stream. When a new container starts (the platform's "Container is waiting to start" line after the container's own lines, or a reconnect that begins with newer lines than were kept), it inserts --- new container (restart N) --- and keeps the old container's last lines above it, which usually show why it stopped. get_logs and the services in get_deployment report restarts_seen and restarted_at.

  • get_deployment services also carry status_changes: the native statuses this MCP process saw, with times, once a service has had more than one.

  • Lines that are only a timestamp are dropped, and identical consecutive lines are collapsed into one with a count ((×5)).

  • A failed build or start puts the last 20 lines into failure.log_tail.

  • get_logs takes image_id, service_id or deployment_id (all its builds and services) and lines (10–50, default 20). It also reads builds and services this MCP did not start, but only while they run.

Waiting for long builds

Builds can run for many minutes. The MCP keeps executing in the background, but an agent that has ended its turn is not told when they finish. dist/wait.js (bin constructor-research-wait) blocks until the given deployments, or all in-progress ones when no ID is given, finish, and prints one line each: status, message, services with public URLs, next step. Exit codes: 0 finished, 2 needs the user (failed, key, upload, volume confirmation), 3 still running at --max-minutes (default 60), 4 nothing in progress.

npx -y -p constructor-research-mcp@latest constructor-research-wait <deployment_id>

It watches the checkpoints the MCP writes. For deployments named by ID, if no process has advanced one for a minute (the MCP was closed), it continues it itself, exactly as the MCP would on restart. Without IDs it only watches, since those deployments may belong to other sessions. While a deployment runs, next_action gives the agent the exact command, including the MCP's non-default CONSTRUCTOR_* settings; the wait command needs the same settings as the MCP.

How the agent learns the outcome depends on the client:

Client

Without setup

Optional wake-up

Claude Code

runs the command in the background; Claude Code wakes the agent when it exits

PostToolUse hook with asyncRewake (merge into settings.json): wakes the agent after any deploy/update/build/start/stop

Codex CLI

runs the command in the foreground (no background wake-up exists)

Stop hook (~/.codex/hooks.json, trust it in /hooks): when the agent would stop, waits up to 9 min, then continues the turn with the outcome, or with "still in progress" so the next stop waits again

OpenCode

runs the command in the foreground

plugin (.opencode/plugins/): after a deploy tool call, waits in the background and sends the outcome as a new message

Hooks report each deployment once: one that had already finished when the tool returned is skipped, and only one waiter per deployment runs. The Codex hook covers every in-progress deployment touched in the last two hours, including ones from other sessions. The Codex and OpenCode add-ons follow their documentation (Codex hooks; OpenCode tool.execute.after and client.session.prompt) and have not yet been run in those clients.

Harness configuration

Examples:

  • Codex CLI: ~/.codex/config.toml or a trusted project's .codex/config.toml.

  • Claude Code: merge into project .mcp.json.

  • OpenCode v1: merge into opencode.json/opencode.jsonc.

  • OpenCode v2: entries live under mcp.servers.

Use the executable directly to keep stdout reserved for MCP. structuredContent contains full results; text content is a short summary to avoid duplicated output.

Disk files

The tools use the disk's WebDAV storage (/api/platform-storage/desks/{disk}/dav/project/) with the same key. sync_files:

  • compares each local file with the disk by size, then by the server's SHA-256 checksum; only new and changed files are sent, and nothing is deleted;

  • uploads new files and creates folders without asking; if existing files would be replaced, it uploads nothing and returns confirm_required with the whole plan, to be approved once and repeated with confirm:true; dry_run:true only previews;

  • uploads each file to a temporary file in .rolos-temp/, in 4 MB chunks (the server rejects single requests above about 9 MB), then moves it into place and verifies the checksum, so a failed upload never leaves a half-written file;

  • skips .git, node_modules, .env, .venv, __pycache__, .DS_Store, symlinks, files over 100 MB, and any exclude patterns;

  • reports a conflict, and does nothing, when a file would replace a folder or the other way round;

  • stops starting new files after about 25 seconds and returns in_progress; repeating the same call continues, because finished files compare as unchanged.

A local folder's contents go into remote_path; a single file keeps its name. local_path must be absolute.

move_path takes every rename/move for a request as moves: [{from, to}]. Without confirm it returns confirm_required with the moves and any that cannot be done (missing source, taken destination, folder into itself); with confirm:true it performs them (WebDAV MOVE with Overwrite: F). It never overwrites; the destination's parent folder must already exist.

delete_path takes every path for a request as paths. Without confirm it returns confirm_required with what would go (folders with file and subfolder counts); with confirm:true it deletes. Paths inside a folder that is also listed are covered by that folder. Folders go with all their contents and there is no undo. The disk root cannot be deleted.

Builds: the build context is the folder containing the Dockerfile (verified live, 28 Oct 2026), so a Dockerfile that builds locally in its folder builds the same way on the platform. Every build gets its own image name in the UI style <service>-v<N> (or the requested build_image name, versioned if already taken).

Confirmation policy: creating folders and uploading new files never ask. Replacing, renaming or deleting asks once per request for the whole list.

A desk nobody opened recently has its file storage stopped (filesystem.status: not_started on the desk; WebDAV answers 502, then 503 while starting). Every file tool and the Dockerfile preflight check this first. If storage is stopped, the MCP starts it with POST /desks/{id}/filesystem (what opening the desk in the browser does) and waits up to 45 s; it took about 27-33 s live. If it is still starting, the tool returns not_ready with nothing changed, and the same call can be repeated.

Storage under load: the gateway answers 502/503/504 now and then. Requests that are safe to repeat are retried three times with backoff (MOVE and DELETE are not; after a failed MOVE the checksum tells whether the file landed). A file whose checksum still fails is left for the next call (in_progress) instead of failing the whole sync. Files this MCP process uploaded or checked are remembered, so a repeated sync does not checksum them again while their size and server time are unchanged. Storage requests run 4 at a time; each call uploads for up to 45 s. A build's local_path upload leaves out files matched by the folder's .dockerignore (not used when it has ! exceptions).

Verification

npm run check
npm test
npm run format:check

Tests build the server first, use a local HTTP simulator and SDK stdio client, and verify background execution without progress calls, public/internal links, recovery, partial overrides, native statuses and secret redaction. Tests never mutate live Constructor resources. Logs, readiness checks, registry imports and rollback remain outside the prototype.

Available Tools

14 tools
build_imageB
Destructive

Build a disk Dockerfile. IDs are generated automatically; omit build storage for the default. Waits up to wait_seconds (default 20), then continues in the background. Check get_deployment for the result. The Dockerfile rules in deploy_app apply.

Inputs: name (required), dockerfile (required), desk_id, desk_url, +4 more.

create_folderB
Destructive

Create a folder on a project disk, including missing parent folders. Existing folders are left unchanged.

Inputs: path (required), desk_id, desk_url, project_id.

delete_pathA
Destructive

Delete files/folders (folders with all contents) on a project disk. Send every path for the request in one call: without confirm it returns what would be deleted (confirm_required) for the user to approve once; repeat with confirm=true. Cannot be undone.

Inputs: paths (required), confirm, desk_id, desk_url, +1 more.

deploy_appA
Destructive

Deploy the WHOLE app in one request: prepare project/disk, build or reuse all images, resolve internal/public service references, configure and start. Runs in the background. IDs are automatic. To resume a failure, send deployment_id and service overrides (for example replacement image_id); successful builds are preserved. On failure, failure.log_tail and get_logs show what the build or service printed. Dockerfile rules: one Dockerfile per service named Dockerfile or .dockerfile; docker-compose is not supported. The Dockerfile must build everything itself; no separate setup script the user runs before the build. The app listens on 0.0.0.0 on a fixed port; only one port per service can be public. Services reach each other through internal references (bare host:port by default, http:// only when scheme is set), never localhost; do not bake compose-style fallback hosts (http://db:5432) into ENV. Files uploaded to a desk lose the executable bit: RUN chmod 0755 any entrypoint script you COPY. In nginx configs use only the IPv4 listen line. A volume belongs to one service; services cannot share a volume. Volume data survives restarts and image changes but is wiped if the service is deleted or the volume is removed or changed. The build context is the folder containing the Dockerfile, exactly like a local docker build in that folder. Test the image locally (docker build/run) before uploading.

Inputs: confirm, desk_url, services, project_id, +7 more.

get_deploymentA
Destructive

With deployment_id, observe/wait for background execution; the MCP owns execution. Each call waits up to wait_seconds (max 20); to wait longer, call again, as often as needed (a loop of get_deployment calls is fine), until execution is finished; do not answer the user while it is still in the background. Services carry status_changes and restarts_seen when the MCP saw the status change or a new container start. After sync_files (or manual upload) set files_uploaded=true; after cookie replacement checking the job resumes it. With no arguments, returns the map of all deployments: every deployment-enabled project with its applications and services (names, native statuses, public URLs, ports). With desk_url or project_id, returns that project's desks, images, hardware and applications; add application_id for one application. resume=false observes only. Never returns environment-variable values.

Inputs: resume, desk_url, project_id, wait_seconds, +3 more.

get_logsA
Read-onlyIdempotent

Last lines (default 20, up to 50) of a build or service log: why a build or start failed, how far a long build got, what a starting service prints. Constructor serves logs only live: a build log while the build runs, a service log for its current container while it runs (both replayed from the start, then streamed). The MCP follows the builds and services it starts or shows and keeps their last 50 lines, so they stay readable after the build ends or the container restarts; anything else can be read only while it runs. When a new container starts, the lines of the one before stay, above a '--- new container' marker, and restarts_seen counts them: that answers whether a service keeps restarting and why. An empty service log on a running service usually means a crash loop.

Inputs: lines, image_id, service_id, deployment_id.

list_filesB
Read-onlyIdempotent

List files and folders on a project disk (the Constructor desk's project folder). Non-recursive by default; recursive=true walks subfolders up to max_entries.

Inputs: path, desk_id, desk_url, recursive, +2 more.

list_imagesA
Read-onlyIdempotent

List images with native build statuses and Dockerfile paths. Optionally filter by disk. Compact results by default; detailed=true returns full image records.

Inputs: desk_id, desk_url, detailed, project_id.

move_pathA
Destructive

Rename or move files/folders on a project disk. Send every move for the request in one call: without confirm it returns the list (confirm_required) for the user to approve once; repeat with confirm=true. Never overwrites; the destination parent folder must exist.

Inputs: moves (required), confirm, desk_id, desk_url, +1 more.

sign_inA
Read-onlyIdempotent

Signs the user in to their Constructor: https://constructor.app unless url names another one (any link from it, e.g. https://acme.constructor.app). Call it when the user asks to sign in, or when a tool returns needs_auth, after telling the user a sign-in window is about to open. It opens a separate Chrome window at the sign-in page; the user signs in there and the window closes by itself. There is one sign-in at a time: signing in to another Constructor replaces it, and the MCP works there afterwards. The session is kept for this harness only, and the MCP renews it automatically for up to 14 days. Waits up to wait_seconds; while the user is still signing in it returns sign_in_pending: call it again (no second window opens), then repeat the call that needed auth.

Inputs: url, force, wait_seconds.

start_appA
Destructive

Start all or selected services as one operation. MCP handles all requests. Waits up to wait_seconds (default 20); remaining execution continues in the background. Started does not mean ready.

Inputs: application_id (required), desk_url, project_id, wait_seconds, +1 more.

stop_appA
Destructive

Stop all or selected services as one operation. MCP handles all requests. Waits up to wait_seconds (default 20). Stopped means stop requests accepted, not verified teardown.

Inputs: application_id (required), desk_url, project_id, wait_seconds, +1 more.

sync_filesA
Destructive

Upload a local file or folder to a project disk. Compares by size and SHA-256 and sends only new and changed files; never deletes. New files and folders upload without asking. If existing files would be replaced, nothing is uploaded and status is confirm_required: ask the user once for the whole list, then repeat with confirm=true. dry_run=true only previews. Skips .git, node_modules, .env, .venv, pycache, .DS_Store and files over 100 MB. If the result is in_progress, repeat the same call to continue.

Inputs: local_path (required), confirm, desk_id, dry_run, +4 more.

update_appA
Destructive

Update/add selected services in one request; preserve omitted settings. MCP handles builds, links and restarts in the background. Environment variables merge; supplied port/volume lists replace their lists. Resume a failed update using deployment_id and service overrides. The Dockerfile rules in deploy_app apply.

Inputs: confirm, desk_url, services, project_id, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target clearly distinct resources/actions (file ops vs image ops vs service lifecycle vs observability). There is some conceptual overlap: deploy_app and update_app both trigger builds that build_image can do standalone, and get_deployment overlaps with get_logs for observing failures, but the descriptions give enough guidance to pick correctly.

    Naming Consistency5/5

    All names are snake_case and verb-first (list_files, build_image, create_folder, sync_files, move_path, delete_path, deploy_app, start_app, get_deployment, get_logs). sign_in is a phrasal verb but fits the same convention cleanly.

    Tool Count5/5

    14 tools is well within the ideal range and each earns its place across file management, image building, deployment lifecycle, and auth. Nothing feels redundant or thin.

    Completeness4/5

    Core workflows are covered: upload/move/delete files, build/list images, deploy/update/start/stop services, observe deployments and logs, and sign in. Minor gaps exist—no tool to read/download file contents from a disk and no image deletion—but agents can work around these.

    Related MCP Connectors

    Related MCP Servers