Clients

Update a client

Edit a client’s display name and/or its config. Two ways to change the config: config replaces it wholesale, and set changes named fields over the config read inside the write transaction — prefer set, because a whole-config round-trip composed from a stale read reverts whatever landed in between.

Config edits require expectedConfigId and renames require expectedName. A stale token is 409 CONFLICT whose details carries the current value: re-read the client and retry. A config edit that resolves to byte-identical settings writes nothing at all.

Guest callers are denied (a write).

PATCH

projects

{projectId}

clients

{client}

Update a client

curl --request PATCH \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedConfigId": "hc_01J8…",
  "set": {
    "temperature": 0.2
  }
}
'

import requests

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

payload = {
    "expectedConfigId": "hc_01J8…",
    "set": { "temperature": 0.2 }
}
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({expectedConfigId: 'hc_01J8…', set: {temperature: 0.2}})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}', 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}/clients/{client}",
  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([
    'expectedConfigId' => 'hc_01J8…',
    'set' => [
        'temperature' => 0.2
    ]
  ]),
  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}/clients/{client}"

	payload := strings.NewReader("{\n  \"expectedConfigId\": \"hc_01J8…\",\n  \"set\": {\n    \"temperature\": 0.2\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}/clients/{client}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedConfigId\": \"hc_01J8…\",\n  \"set\": {\n    \"temperature\": 0.2\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"expectedConfigId\": \"hc_01J8…\",\n  \"set\": {\n    \"temperature\": 0.2\n  }\n}"

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

{
  "id": "<string>",
  "name": "<string>",
  "config": {},
  "ownerScope": {},
  "configId": "<string>",
  "hasComputer": true,
  "createdAt": 123,
  "updatedAt": 123,
  "impact": {
    "liveEnvironmentCount": 123,
    "scenarioAttachmentCount": 123,
    "activeLegacyJourneyCount": 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.

client

string

required

Client name or ID. A name is matched case-insensitively and must be unique in the project; an ambiguous name is refused with 409 CONFLICT listing the candidate ids rather than resolved to one of them.

Body

application/json

Option 1
Option 2
Option 3

Edit a client. Provide at least one of name, config (whole-config replacement) or set (named fields); config and set are mutually exclusive. Config edits require expectedConfigId and renames require expectedName, so a concurrent edit is rejected rather than overwritten.

name

string

required

New display name.

Minimum string length: 1

expectedName

string

The name you last read for this client. REQUIRED whenever the request sends name: a rename does not rotate the config, so expectedConfigId cannot detect a concurrent one. A mismatch is 409 CONFLICT carrying details.currentName.

Minimum string length: 1

expectedConfigId

string

The configId you last read for this client. REQUIRED whenever the request changes the config (config or set): without it a write composed from a stale read silently reverts whatever landed in between. A mismatch is 409 CONFLICT carrying details.currentConfigId.

Minimum string length: 1

expectedImpact

object

The impact you last read for this client. Optional, and checked transactionally when sent — a consumer added or removed since you read it makes the write conflict (details.currentImpact) instead of quietly affecting more than you were told it would.

Show child attributes

config

object

Replacement client config v2. Replaces the config wholesale; use set to change named fields instead.

set

object

Named fields to change, applied over the client's current config INSIDE the write transaction. Absent always means keep. null means "make it go away", and what that means depends on the field: a required field resets to its documented default, an optional one clears to absent. Object-valued fields are whole-object replacements, not merges — to change a deep knob, read the client, overlay the sub-object, and send it back whole. hostStyle, clientCapabilities, hostContext and server membership are deliberately not settable here (use a whole-config replacement, or the servers operation).

Show child attributes

Response

The updated client settings.

A client plus its resolved config (model, capabilities, host context, MCP profile) and the read-backs an editor needs.

string

required

name

string

required

config

object

required

Client config v2 DTO. Opaque object; shape mirrors the inspector's client editor.

ownerScope

object | null

required

configId

string

The concurrency token — see Client.configId.

hasComputer

boolean

createdAt

number

Unix epoch milliseconds.

updatedAt

number

Unix epoch milliseconds.

impact

object

What a config edit to this client would follow. These are the DURABLE consumers that re-resolve the client's current config; past runs, per-turn traces and pinned eval-suite snapshots hold a config id and are unaffected. Direct playground and client-chat use follows the edit too and has no row to count.

Show child attributes

⌘I

Update a client

curl --request PATCH \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedConfigId": "hc_01J8…",
  "set": {
    "temperature": 0.2
  }
}
'

import requests

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

payload = {
    "expectedConfigId": "hc_01J8…",
    "set": { "temperature": 0.2 }
}
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({expectedConfigId: 'hc_01J8…', set: {temperature: 0.2}})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}', 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}/clients/{client}",
  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([
    'expectedConfigId' => 'hc_01J8…',
    'set' => [
        'temperature' => 0.2
    ]
  ]),
  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}/clients/{client}"

	payload := strings.NewReader("{\n  \"expectedConfigId\": \"hc_01J8…\",\n  \"set\": {\n    \"temperature\": 0.2\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}/clients/{client}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedConfigId\": \"hc_01J8…\",\n  \"set\": {\n    \"temperature\": 0.2\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"expectedConfigId\": \"hc_01J8…\",\n  \"set\": {\n    \"temperature\": 0.2\n  }\n}"

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

{
  "id": "<string>",
  "name": "<string>",
  "config": {},
  "ownerScope": {},
  "configId": "<string>",
  "hasComputer": true,
  "createdAt": 123,
  "updatedAt": 123,
  "impact": {
    "liveEnvironmentCount": 123,
    "scenarioAttachmentCount": 123,
    "activeLegacyJourneyCount": 123
  }
}

API Guides

Endpoints

Update a client

Authorizations

Path Parameters

Body

Response