Update an environment

PATCH

projects

{projectId}

environments

{environmentId}

Update an environment

curl --request PATCH \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedRevision": 1,
  "name": "<string>",
  "description": "<string>",
  "hostId": "<string>",
  "serverAttachmentId": "<string>",
  "skillSelection": {
    "mode": "explicit",
    "skillIds": [
      "<string>"
    ]
  },
  "pluginVersionIds": [
    "<string>"
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}"

payload = {
    "expectedRevision": 1,
    "name": "<string>",
    "description": "<string>",
    "hostId": "<string>",
    "serverAttachmentId": "<string>",
    "skillSelection": {
        "mode": "explicit",
        "skillIds": ["<string>"]
    },
    "pluginVersionIds": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    expectedRevision: 1,
    name: '<string>',
    description: '<string>',
    hostId: '<string>',
    serverAttachmentId: '<string>',
    skillSelection: {mode: 'explicit', skillIds: ['<string>']},
    pluginVersionIds: ['<string>']
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'expectedRevision' => 1,
    'name' => '<string>',
    'description' => '<string>',
    'hostId' => '<string>',
    'serverAttachmentId' => '<string>',
    'skillSelection' => [
        'mode' => 'explicit',
        'skillIds' => [
                '<string>'
        ]
    ],
    'pluginVersionIds' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}"

	payload := strings.NewReader("{\n  \"expectedRevision\": 1,\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"serverAttachmentId\": \"<string>\",\n  \"skillSelection\": {\n    \"mode\": \"explicit\",\n    \"skillIds\": [\n      \"<string>\"\n    ]\n  },\n  \"pluginVersionIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedRevision\": 1,\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"serverAttachmentId\": \"<string>\",\n  \"skillSelection\": {\n    \"mode\": \"explicit\",\n    \"skillIds\": [\n      \"<string>\"\n    ]\n  },\n  \"pluginVersionIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expectedRevision\": 1,\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"serverAttachmentId\": \"<string>\",\n  \"skillSelection\": {\n    \"mode\": \"explicit\",\n    \"skillIds\": [\n      \"<string>\"\n    ]\n  },\n  \"pluginVersionIds\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "projectId": "<string>",
  "name": "<string>",
  "hostId": "<string>",
  "revision": 123,
  "archived": true,
  "createdAt": 123,
  "updatedAt": 123,
  "description": "<string>",
  "serverAttachmentId": "<string>",
  "skillSelection": {
    "mode": "explicit",
    "skillIds": [
      "<string>"
    ]
  },
  "pluginVersionIds": [
    "<string>"
  ],
  "archivedAt": 123
}

Authorizations

Authorization

string

header

required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Path Parameters

projectId

string

required

ID of the hosted project that contains the server.

environmentId

string

required

Project environment ID, as returned by the project's environment list.

Body

application/json

Only the fields you send change. serverAttachmentId, skillSelection, and pluginVersionIds are three-state: omit to leave unchanged, send null to CLEAR, send a value to set. An empty array is rejected — it is not a way to clear. Send at least one field besides expectedRevision. Unknown fields are rejected.

expectedRevision

integer

required

The revision you last read. If the environment changed since, the write is rejected with 409 rather than clobbering the other edit.

Required range: x >= 0

name

string

Minimum string length: 1

description

string

Send an empty string to clear the description.

hostId

string

serverAttachmentId

string | null

null clears the pin and falls back to the host config's servers.

skillSelection

object | null

null clears the pinned skill selection.

Show child attributes

pluginVersionIds

string[] | null

Pinned plugin VERSION IDs. Narrow by design: the plugin must be installed and enabled, the version must be ready, at most one version per plugin may be pinned, and none of its skills may carry supporting files. Not a general-purpose plugin list. null clears all pins.

Minimum array length: 1

Response

The updated environment.

A project environment: a named, live-editable execution bundle that eval suites and journeys run against.

string

required

projectId

string

required

name

string

required

Unique among the project's live (non-archived) environments.

hostId

string

required

The host this environment runs against.

revision

integer

required

Optimistic-concurrency counter. Pass this back as expectedRevision on the next write; if it no longer matches, the write is rejected with 409 instead of overwriting a concurrent edit.

archived

boolean

required

Archived environments cannot be edited or launched until restored.

createdAt

number

required

Unix epoch milliseconds.

updatedAt

number

required

Unix epoch milliseconds.

description

string

serverAttachmentId

string

Present only when the environment pins a standalone server group; otherwise the host config's own servers apply.

skillSelection

object

An explicit pinned skill selection. Cannot be empty — clear the field instead (send null on update) to mean "no pinned skills".

Show child attributes

pluginVersionIds

string[]

archivedAt

number

Unix epoch milliseconds. Present only when archived.

Preview what an environment resolves toResolve an environment to the exact execution inputs a run would use right now: the host's current config, the closed server set (including servers contributed by pinned plugin versions), and the resolved plugin versions. Returns 409 when the environment cannot currently produce a runnable configuration — for example a pinned plugin was disabled or deleted; `details.code` carries the specific reason (`ENV_PLUGIN_UNAVAILABLE`, `ENV_NO_SERVERS`, `ENV_HOST_MISSING`, …).

⌘I

Update an environment

curl --request PATCH \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedRevision": 1,
  "name": "<string>",
  "description": "<string>",
  "hostId": "<string>",
  "serverAttachmentId": "<string>",
  "skillSelection": {
    "mode": "explicit",
    "skillIds": [
      "<string>"
    ]
  },
  "pluginVersionIds": [
    "<string>"
  ]
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}"

payload = {
    "expectedRevision": 1,
    "name": "<string>",
    "description": "<string>",
    "hostId": "<string>",
    "serverAttachmentId": "<string>",
    "skillSelection": {
        "mode": "explicit",
        "skillIds": ["<string>"]
    },
    "pluginVersionIds": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    expectedRevision: 1,
    name: '<string>',
    description: '<string>',
    hostId: '<string>',
    serverAttachmentId: '<string>',
    skillSelection: {mode: 'explicit', skillIds: ['<string>']},
    pluginVersionIds: ['<string>']
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'expectedRevision' => 1,
    'name' => '<string>',
    'description' => '<string>',
    'hostId' => '<string>',
    'serverAttachmentId' => '<string>',
    'skillSelection' => [
        'mode' => 'explicit',
        'skillIds' => [
                '<string>'
        ]
    ],
    'pluginVersionIds' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}"

	payload := strings.NewReader("{\n  \"expectedRevision\": 1,\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"serverAttachmentId\": \"<string>\",\n  \"skillSelection\": {\n    \"mode\": \"explicit\",\n    \"skillIds\": [\n      \"<string>\"\n    ]\n  },\n  \"pluginVersionIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedRevision\": 1,\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"serverAttachmentId\": \"<string>\",\n  \"skillSelection\": {\n    \"mode\": \"explicit\",\n    \"skillIds\": [\n      \"<string>\"\n    ]\n  },\n  \"pluginVersionIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/environments/{environmentId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expectedRevision\": 1,\n  \"name\": \"<string>\",\n  \"description\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"serverAttachmentId\": \"<string>\",\n  \"skillSelection\": {\n    \"mode\": \"explicit\",\n    \"skillIds\": [\n      \"<string>\"\n    ]\n  },\n  \"pluginVersionIds\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "projectId": "<string>",
  "name": "<string>",
  "hostId": "<string>",
  "revision": 123,
  "archived": true,
  "createdAt": 123,
  "updatedAt": 123,
  "description": "<string>",
  "serverAttachmentId": "<string>",
  "skillSelection": {
    "mode": "explicit",
    "skillIds": [
      "<string>"
    ]
  },
  "pluginVersionIds": [
    "<string>"
  ],
  "archivedAt": 123
}

API Guides

Endpoints

Authorizations

Path Parameters

Body

Response