Chat sessions

Send one agent Playground message

Send one message to a project’s MCP servers and get the model’s reply plus the telemetry a participant in the conversation could not see: which tools ran, with what arguments, what each returned, per-call latency, and token usage.

Spends model credits per call. idempotencyKey is required and must be STABLE for the triggering intent — a fresh key per HTTP attempt deduplicates nothing, so a timeout-and-retry would run and bill the turn twice. With a stable key, a retry replays the completed turn.

Omit sessionId to start a session; pass the one this returns to continue it. Configuration (modelId, target, systemPrompt, toolMode) pins on the FIRST turn — a continuation that resends any of it is refused with details.reason: "CONFIG_ON_CONTINUATION".

Only sessions created through this endpoint may be continued through it (CONTINUATION_NOT_ALLOWED): appending to a human’s live Playground session would interleave two writers on one transcript.

toolMode defaults to read_only, which advertises only tools the server annotated readOnlyHint: true. That hint is server-asserted, so read_only is a policy this host applies, not a guarantee it can verify. auto advertises everything and may cause real external side effects through arbitrary third-party tools.

Pass hostId — or target an environmentId, which pins its own host — to run the turn AS a saved host. That is what selects the ENGINE: a host declaring an agent harness runs the real runtime, and one that cannot run here is refused BEFORE it spends (422, details.reason: "HARNESS_UNAVAILABLE", with details.kind naming the rule that refused) rather than quietly downgraded to the emulated engine. Every response names what actually ran in engine. hostId is per-turn and cannot be pinned, so a continuation of a session that named ONLY a host must re-send it — omitting it is a 400 with details.reason: "HOST_TARGET_REQUIRED", never a quiet fall back to the emulated engine.

POST

chat-sessions

messages

Send one agent Playground message

curl --request POST \
  --url https://app.mcpjam.com/api/v1/chat-sessions/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "<string>",
  "message": "<string>",
  "projectId": "<string>",
  "sessionId": "<string>",
  "modelId": "<string>",
  "hostId": "<string>",
  "environmentId": "<string>",
  "serverIds": [
    "<string>"
  ],
  "systemPrompt": "<string>",
  "temperature": 1,
  "maxSteps": 8,
  "toolMode": "read_only",
  "allowedServerIds": [
    "<string>"
  ],
  "allowedTools": [
    "<string>"
  ],
  "maxToolCalls": 8
}
'

import requests

url = "https://app.mcpjam.com/api/v1/chat-sessions/messages"

payload = {
    "idempotencyKey": "<string>",
    "message": "<string>",
    "projectId": "<string>",
    "sessionId": "<string>",
    "modelId": "<string>",
    "hostId": "<string>",
    "environmentId": "<string>",
    "serverIds": ["<string>"],
    "systemPrompt": "<string>",
    "temperature": 1,
    "maxSteps": 8,
    "toolMode": "read_only",
    "allowedServerIds": ["<string>"],
    "allowedTools": ["<string>"],
    "maxToolCalls": 8
}
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({
    idempotencyKey: '<string>',
    message: '<string>',
    projectId: '<string>',
    sessionId: '<string>',
    modelId: '<string>',
    hostId: '<string>',
    environmentId: '<string>',
    serverIds: ['<string>'],
    systemPrompt: '<string>',
    temperature: 1,
    maxSteps: 8,
    toolMode: 'read_only',
    allowedServerIds: ['<string>'],
    allowedTools: ['<string>'],
    maxToolCalls: 8
  })
};

fetch('https://app.mcpjam.com/api/v1/chat-sessions/messages', 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/chat-sessions/messages",
  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([
    'idempotencyKey' => '<string>',
    'message' => '<string>',
    'projectId' => '<string>',
    'sessionId' => '<string>',
    'modelId' => '<string>',
    'hostId' => '<string>',
    'environmentId' => '<string>',
    'serverIds' => [
        '<string>'
    ],
    'systemPrompt' => '<string>',
    'temperature' => 1,
    'maxSteps' => 8,
    'toolMode' => 'read_only',
    'allowedServerIds' => [
        '<string>'
    ],
    'allowedTools' => [
        '<string>'
    ],
    'maxToolCalls' => 8
  ]),
  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/chat-sessions/messages"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"message\": \"<string>\",\n  \"projectId\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"temperature\": 1,\n  \"maxSteps\": 8,\n  \"toolMode\": \"read_only\",\n  \"allowedServerIds\": [\n    \"<string>\"\n  ],\n  \"allowedTools\": [\n    \"<string>\"\n  ],\n  \"maxToolCalls\": 8\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/chat-sessions/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"message\": \"<string>\",\n  \"projectId\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"temperature\": 1,\n  \"maxSteps\": 8,\n  \"toolMode\": \"read_only\",\n  \"allowedServerIds\": [\n    \"<string>\"\n  ],\n  \"allowedTools\": [\n    \"<string>\"\n  ],\n  \"maxToolCalls\": 8\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/chat-sessions/messages")

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  \"idempotencyKey\": \"<string>\",\n  \"message\": \"<string>\",\n  \"projectId\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"temperature\": 1,\n  \"maxSteps\": 8,\n  \"toolMode\": \"read_only\",\n  \"allowedServerIds\": [\n    \"<string>\"\n  ],\n  \"allowedTools\": [\n    \"<string>\"\n  ],\n  \"maxToolCalls\": 8\n}"

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

{
  "sessionId": "<string>",
  "turnId": "<string>",
  "projectId": "<string>",
  "persisted": {
    "outcome": "<string>",
    "version": 123
  },
  "origin": "api",
  "reply": "<string>",
  "finishReason": "<string>",
  "toolCalls": [
    {
      "toolCallId": "<string>",
      "toolName": "<string>",
      "input": "<unknown>",
      "status": "ok",
      "output": "<unknown>",
      "errorMessage": "<string>",
      "truncated": true
    }
  ],
  "trace": {
    "turnId": "<string>",
    "spanCount": 123,
    "spans": [
      {}
    ]
  },
  "usage": {
    "inputTokens": 123,
    "outputTokens": 123,
    "totalTokens": 123
  },
  "model": {
    "id": "<string>",
    "provider": "<string>"
  },
  "toolMode": "read_only",
  "engine": "<string>",
  "hostId": "<string>",
  "advertisedToolCount": 123,
  "excludedToolCount": 123,
  "replay": true,
  "message": "<string>"
}

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.

Body

application/json

idempotencyKey

string

required

STABLE identity for this turn's intent — reuse it when retrying. A fresh key per attempt deduplicates nothing and will bill the turn twice. Printable ASCII only.

Required string length: 1 - 200

message

string

required

The message to send, as the user.

Required string length: 1 - 8000

projectId

string

Required to START a session; ignored when continuing one.

sessionId

string

Continue this session. Omit to start a new one.

modelId

string

Provider-prefixed model id, e.g. anthropic/claude-sonnet-5. Required on a first turn. A BARE id is rejected with details.reason: "MODEL_AMBIGUOUS" rather than guessed — an unprefixed id is indistinguishable from a local Ollama model, and guessing would spend on the wrong rail.

hostId

string

The saved host (client) this turn executes AS — it decides which ENGINE runs. A host that declares an agent harness (Claude Code, Codex, Cursor CLI) runs the real runtime; without one the turn runs MCPJam's emulated engine. The server re-fetches that host's own runtime config, so harness and computer are NEVER read from the request body — a body carrying either is a 400. PER-TURN, not pinned to the session: re-send it on every turn, and read engine on the response to confirm what ran. A continuation of a session that named ONLY a host must re-send it — omitting it is refused with details.reason: "HOST_TARGET_REQUIRED" rather than run on the emulated engine. Alongside environmentId it is an assertion only — a host contradicting the environment's own is rejected with details.reason: "HOST_TARGET_CONFLICT". Alone, the turn connects the host's own selected servers. A harness turn additionally requires toolMode: "auto" with no allowedTools/maxToolCalls: a harness builds its own tool set inside its sandbox, so the narrowing could not be applied, and the combination is refused rather than run with it silently dropped. It also cannot be combined with serverIds, because hostId cannot be pinned beside them and a later turn that omitted it would run the emulated engine on a session established on the harness (422, details.kind: "surface-unpinnable-host") — target an environmentId, or send hostId alone and narrow per turn with allowedServerIds.

environmentId

string

Target this environment's servers. Mutually exclusive with serverIds. First turn only.

serverIds

string[]

Target these project servers. Mutually exclusive with environmentId. First turn only. Server CONFIGS are never accepted — only ids the project already holds.

Maximum array length: 20

systemPrompt

string

First turn only.

Maximum string length: 8000

temperature

number

First turn only — pinned to the session and reused on every continuation.

Required range: 0 <= x <= 2

maxSteps

integer

Required range: 1 <= x <= 16

toolMode

enum<string>

default:read_only

read_only advertises only tools annotated readOnlyHint: true. auto advertises everything and MAY CAUSE REAL EXTERNAL SIDE EFFECTS. First turn only.

Available options:

read_only,

auto

allowedServerIds

string[]

Narrow THIS TURN to a subset of the target's servers. An empty array narrows to none and is rejected — omit the field to use the whole target. Per-turn, not pinned.

Maximum array length: 20

allowedTools

string[]

Advertise only these tool names, for THIS TURN. An empty array advertises no tools at all — the same request as maxToolCalls: 0. Per-turn, not pinned.

Maximum array length: 100

maxToolCalls

integer

Cap the tool calls this turn may make, enforced at DISPATCH rather than by bounding steps (one step can emit several parallel calls). 0 advertises no tools at all.

Required range: 0 <= x <= 16

Response

The turn ran. persisted.outcome reports whether the transcript landed — a turn that ran but failed to persist still spent, so this is a 200 with an honest persisted block rather than an error.

sessionId

string | null

required

The one public session id. Pass it back to continue, and to the trace/detail reads. NULL only when the turn ran but its transcript did not persist — which persisted.outcome reports, and which must not be read as "nothing happened": the turn already spent.

turnId

string

required

Minted by the turn lease and used by the ingest dedupe, so it names the same turn in both.

projectId

string

required

The project this turn ran in. On a continuation the caller never sent it — it comes off the session row — so this is the only place the response names the session's project.

persisted

object

required

Show child attributes

origin

enum<string>

required

Available options:

api

string

finishReason

string | null

toolCalls

object[]

Show child attributes

trace

object

This turn's spans, inline.

Show child attributes

usage

object

Show child attributes

model

object

Show child attributes

toolMode

enum<string>

Available options:

read_only,

auto

engine

string

WHICH ENGINE RAN: emulated, or harness:<id> such as harness:claude-code. Present on every turn. Read it rather than infer it from model. hostId is per-turn: a continuation of a host-only session is refused without it, and one that pinned its own serverIds runs the emulated engine — this is the field that says which.

hostId

string

The saved host this turn executed as — the pointer the caller sent, or the host the targeted environment pins. Absent when the turn named no host.

advertisedToolCount

integer

Tools the model could see this turn.

excludedToolCount

integer

Tools the tool policy withheld.

replay

boolean

Set when this idempotencyKey replayed an already-completed turn. Nothing was spent.

message

string

⌘I

Send one agent Playground message

curl --request POST \
  --url https://app.mcpjam.com/api/v1/chat-sessions/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "<string>",
  "message": "<string>",
  "projectId": "<string>",
  "sessionId": "<string>",
  "modelId": "<string>",
  "hostId": "<string>",
  "environmentId": "<string>",
  "serverIds": [
    "<string>"
  ],
  "systemPrompt": "<string>",
  "temperature": 1,
  "maxSteps": 8,
  "toolMode": "read_only",
  "allowedServerIds": [
    "<string>"
  ],
  "allowedTools": [
    "<string>"
  ],
  "maxToolCalls": 8
}
'

import requests

url = "https://app.mcpjam.com/api/v1/chat-sessions/messages"

payload = {
    "idempotencyKey": "<string>",
    "message": "<string>",
    "projectId": "<string>",
    "sessionId": "<string>",
    "modelId": "<string>",
    "hostId": "<string>",
    "environmentId": "<string>",
    "serverIds": ["<string>"],
    "systemPrompt": "<string>",
    "temperature": 1,
    "maxSteps": 8,
    "toolMode": "read_only",
    "allowedServerIds": ["<string>"],
    "allowedTools": ["<string>"],
    "maxToolCalls": 8
}
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({
    idempotencyKey: '<string>',
    message: '<string>',
    projectId: '<string>',
    sessionId: '<string>',
    modelId: '<string>',
    hostId: '<string>',
    environmentId: '<string>',
    serverIds: ['<string>'],
    systemPrompt: '<string>',
    temperature: 1,
    maxSteps: 8,
    toolMode: 'read_only',
    allowedServerIds: ['<string>'],
    allowedTools: ['<string>'],
    maxToolCalls: 8
  })
};

fetch('https://app.mcpjam.com/api/v1/chat-sessions/messages', 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/chat-sessions/messages",
  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([
    'idempotencyKey' => '<string>',
    'message' => '<string>',
    'projectId' => '<string>',
    'sessionId' => '<string>',
    'modelId' => '<string>',
    'hostId' => '<string>',
    'environmentId' => '<string>',
    'serverIds' => [
        '<string>'
    ],
    'systemPrompt' => '<string>',
    'temperature' => 1,
    'maxSteps' => 8,
    'toolMode' => 'read_only',
    'allowedServerIds' => [
        '<string>'
    ],
    'allowedTools' => [
        '<string>'
    ],
    'maxToolCalls' => 8
  ]),
  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/chat-sessions/messages"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"message\": \"<string>\",\n  \"projectId\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"temperature\": 1,\n  \"maxSteps\": 8,\n  \"toolMode\": \"read_only\",\n  \"allowedServerIds\": [\n    \"<string>\"\n  ],\n  \"allowedTools\": [\n    \"<string>\"\n  ],\n  \"maxToolCalls\": 8\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/chat-sessions/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"message\": \"<string>\",\n  \"projectId\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"temperature\": 1,\n  \"maxSteps\": 8,\n  \"toolMode\": \"read_only\",\n  \"allowedServerIds\": [\n    \"<string>\"\n  ],\n  \"allowedTools\": [\n    \"<string>\"\n  ],\n  \"maxToolCalls\": 8\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/chat-sessions/messages")

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  \"idempotencyKey\": \"<string>\",\n  \"message\": \"<string>\",\n  \"projectId\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"modelId\": \"<string>\",\n  \"hostId\": \"<string>\",\n  \"environmentId\": \"<string>\",\n  \"serverIds\": [\n    \"<string>\"\n  ],\n  \"systemPrompt\": \"<string>\",\n  \"temperature\": 1,\n  \"maxSteps\": 8,\n  \"toolMode\": \"read_only\",\n  \"allowedServerIds\": [\n    \"<string>\"\n  ],\n  \"allowedTools\": [\n    \"<string>\"\n  ],\n  \"maxToolCalls\": 8\n}"

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

{
  "sessionId": "<string>",
  "turnId": "<string>",
  "projectId": "<string>",
  "persisted": {
    "outcome": "<string>",
    "version": 123
  },
  "origin": "api",
  "reply": "<string>",
  "finishReason": "<string>",
  "toolCalls": [
    {
      "toolCallId": "<string>",
      "toolName": "<string>",
      "input": "<unknown>",
      "status": "ok",
      "output": "<unknown>",
      "errorMessage": "<string>",
      "truncated": true
    }
  ],
  "trace": {
    "turnId": "<string>",
    "spanCount": 123,
    "spans": [
      {}
    ]
  },
  "usage": {
    "inputTokens": 123,
    "outputTokens": 123,
    "totalTokens": 123
  },
  "model": {
    "id": "<string>",
    "provider": "<string>"
  },
  "toolMode": "read_only",
  "engine": "<string>",
  "hostId": "<string>",
  "advertisedToolCount": 123,
  "excludedToolCount": 123,
  "replay": true,
  "message": "<string>"
}

API Guides

Endpoints

Send one agent Playground message

Authorizations

Body

Response