Clients

Create a client (from a template or a full config)

Creates a client in the project and responds 201 with the new client’s detail. Seed the config one of two ways: pass template (a built-in template id, optional theme) to seed server-side from the live backend client-template catalog, falling back to the bundled SDK catalog snapshot if the live catalog is unavailable, OR pass config (a full client config v2). Exactly one of template or config is required.

Guest callers are denied (client creation is a write).

POST

projects

{projectId}

clients

Create a client (from a template or a full config)

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/clients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Claude",
  "template": "claude",
  "theme": "dark"
}
'

import requests

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

payload = {
    "name": "Claude",
    "template": "claude",
    "theme": "dark"
}
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({name: 'Claude', template: 'claude', theme: 'dark'})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/clients', 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",
  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([
    'name' => 'Claude',
    'template' => 'claude',
    'theme' => 'dark'
  ]),
  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"

	payload := strings.NewReader("{\n  \"name\": \"Claude\",\n  \"template\": \"claude\",\n  \"theme\": \"dark\"\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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Claude\",\n  \"template\": \"claude\",\n  \"theme\": \"dark\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"name\": \"Claude\",\n  \"template\": \"claude\",\n  \"theme\": \"dark\"\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.

Body

application/json

Option 1
Option 2

Create a client from a built-in template OR a full config. Exactly one of template or config is required.

name

string

required

Display name for the new client.

template

enum<string>

required

Built-in template id to seed the host config from.

Available options:

mcpjam,

claude,

claude-code,

chatgpt,

mistral,

cursor,

codex,

copilot,

vscode,

agentcore,

n8n,

perplexity

theme

enum<string>

Theme stamped into the seeded config (template only).

Available options:

light,

dark

config

object

Full client config v2, used verbatim (alternative to template). Must pin modelId.

Show child attributes

Response

The client was created.

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

Create a client (from a template or a full config)

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/clients \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Claude",
  "template": "claude",
  "theme": "dark"
}
'

import requests

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

payload = {
    "name": "Claude",
    "template": "claude",
    "theme": "dark"
}
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({name: 'Claude', template: 'claude', theme: 'dark'})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/clients', 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",
  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([
    'name' => 'Claude',
    'template' => 'claude',
    'theme' => 'dark'
  ]),
  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"

	payload := strings.NewReader("{\n  \"name\": \"Claude\",\n  \"template\": \"claude\",\n  \"theme\": \"dark\"\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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Claude\",\n  \"template\": \"claude\",\n  \"theme\": \"dark\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"name\": \"Claude\",\n  \"template\": \"claude\",\n  \"theme\": \"dark\"\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

Create a client (from a template or a full config)

Authorizations

Path Parameters

Body

Response