Environments

Get or create an unnamed environment for a composed stack

Changed on

GET-OR-CREATE an UNNAMED, content-addressed environment for a composed stack — a host plus an optional server group, model override, computer image and pinned skills.

Distinct from POST /environments, which mints a NAMED row that lands in the project's environment list forever. A composed stack is a throwaway: the caller wants to run this exact combination, not to add a permanent entry someone else has to reason about.

Deduplicated by a server-side fingerprint of the stack, so the same stack always returns the same environment. created says which happened — the status is 200 either way, because get-or-create cannot honestly answer 201 on the dedupe path.

A deployment that predates ad-hoc environments answers 400 with details.reason: "ADHOC_UNAVAILABLE".

Requires project membership (admin only when the stack pins plugin versions). Promote one to a named environment with POST /environments/{environmentId}/name.

post/projects/{projectId}/environments/ensure-adhoc

Request

  • Base URL
    https://app.mcpjam.com/api/v1
  • URL
    https://app.mcpjam.com/api/v1/projects/{projectId}/environments/ensure-adhoc
  • Auth
    HTTP bearer

Path parameters

projectIdstring required

ID of the hosted project that contains the server.

Request body

hostIdstring required

The host the stack runs as.

serverAttachmentIdstring

Standalone server group to pin. Omit to use the host's own servers.

modelIdstring

Model to run instead of the host's pinned one. Stored verbatim.

pluginVersionIdsstring[]

Pinning plugin versions requires project ADMIN; the rest of a stack needs only membership.

sandboxImageIdstring

Project-shared sandbox image to pin, so runs boot a fresh computer from it.

Response

The environment for this stack, created or reused.

createdboolean required

false when the same stack had already been composed. The only way to tell a first compose from a repeat — the status line cannot, because get-or-create answers 200 either way.

Changes

  • 9826d734d268Revision changes
    • breaking

      added to the request property allOf list

    • warning

      removed from the request property allOf list

    • info

      added the optional property / to the response with the status

    • info

      the response optional property / became read-only for the status

    • info

      added to the / response property allOf list for the response status

    • info

      removed from the / response property allOf list for the response status

  • c9e609871357Revision changes
    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status