Replace a client's servers

POST

projects

{projectId}

clients

{client}

servers

Replace a client's servers

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}/servers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serverIds": [
    "<string>"
  ],
  "expectedConfigId": "<string>",
  "optionalServerIds": [
    "<string>"
  ]
}
'

import requests

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

payload = {
    "serverIds": ["<string>"],
    "expectedConfigId": "<string>",
    "optionalServerIds": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serverIds: ['<string>'],
    expectedConfigId: '<string>',
    optionalServerIds: ['<string>']
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}/servers', 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}/servers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'serverIds' => [
        '<string>'
    ],
    'expectedConfigId' => '<string>',
    'optionalServerIds' => [
        '<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}/clients/{client}/servers"

	payload := strings.NewReader("{\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"expectedConfigId\": \"<string>\",\n  \"optionalServerIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}/servers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"expectedConfigId\": \"<string>\",\n  \"optionalServerIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"expectedConfigId\": \"<string>\",\n  \"optionalServerIds\": [\n    \"<string>\"\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

Replaces the client's server attachments wholesale. Every id must name a live server in the same project. Per-server connection overrides are trimmed to the surviving selection.

serverIds

string[]

required

expectedConfigId

string

required

The configId you last read for this client. ALWAYS required here: this operation rewrites the config, and without the token 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

optionalServerIds

string[]

Attached but not required to connect.

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

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

Replace a client's servers

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}/servers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serverIds": [
    "<string>"
  ],
  "expectedConfigId": "<string>",
  "optionalServerIds": [
    "<string>"
  ]
}
'

import requests

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

payload = {
    "serverIds": ["<string>"],
    "expectedConfigId": "<string>",
    "optionalServerIds": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    serverIds: ['<string>'],
    expectedConfigId: '<string>',
    optionalServerIds: ['<string>']
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}/servers', 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}/servers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'serverIds' => [
        '<string>'
    ],
    'expectedConfigId' => '<string>',
    'optionalServerIds' => [
        '<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}/clients/{client}/servers"

	payload := strings.NewReader("{\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"expectedConfigId\": \"<string>\",\n  \"optionalServerIds\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://app.mcpjam.com/api/v1/projects/{projectId}/clients/{client}/servers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"expectedConfigId\": \"<string>\",\n  \"optionalServerIds\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"expectedConfigId\": \"<string>\",\n  \"optionalServerIds\": [\n    \"<string>\"\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

Authorizations

Path Parameters

Body

Response