Studies

Get a study

One study’s full read: execution settings (model, system prompt, tool-approval policy, attached servers, share link), the environment it publishes, and the insights envelope over its latest analyzed window.

environmentId and insights depend on the CALLER, not on the study: both need workspace membership, so a share-link visitor receives the settings without them rather than an error. They are ABSENT in that case, never null — null would claim the study publishes no environment, which is never true.

A study that exists but belongs to a different project reads as 404 NOT_FOUND.

Replaces the deprecated getScenario (settings only) and getUserTestingScenario (envelope only).

GET

projects

{projectId}

studies

{studyId}

Get a study

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/studies/{studyId} \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/studies/{studyId}', 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}/studies/{studyId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "name": "<string>",
  "serverCount": 123,
  "serverNames": [
    "<string>"
  ],
  "requireToolApproval": true,
  "servers": [
    {
      "id": "<string>",
      "name": "<string>",
      "useOAuth": true,
      "url": "<string>"
    }
  ],
  "environmentId": "<string>",
  "insights": {},
  "projectId": "<string>",
  "description": "<string>",
  "mode": "project_members",
  "hostStyle": "<string>",
  "hostId": "<string>",
  "hostName": "<string>",
  "link": {
    "path": "<string>",
    "url": "<string>"
  },
  "createdAt": 123,
  "updatedAt": 123,
  "modelId": "<string>",
  "systemPrompt": "<string>",
  "temperature": 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.

studyId

string

required

Study ID, as returned by publishing an environment or by the project's study reads.

Response

The study.

A study's full read-only settings: the summary fields plus the host execution config and resolved servers.

string

required

name

string

required

serverCount

integer

required

serverNames

string[]

required

requireToolApproval

boolean

required

servers

object[]

required

Show child attributes

environmentId

string | null

The environment this study publishes. ABSENT — not null — when the caller may not see it, which is the case for a share-link visitor: null would claim the study publishes no environment, which is never true.

insights

object

Findings aggregated over the latest analyzed window of real visitor sessions. Absent when the caller may not have it, and on a deployment that predates the envelope — the two degrade identically, and absence means not_available, never "no findings".

projectId

string | null

description

string | null

mode

enum<string> | null

Who can use the study.

Available options:

project_members,

invited_only,

anyone_with_link,

null

hostStyle

string | null

Chat surface style the study renders (e.g. claude, chatgpt).

hostId

string | null

The named host the study publishes (hosts and studies are 1:1).

hostName

string | null

link

object | null

Share link for the study. The URL embeds the access token; visible to any caller who can read the study (the same audience that sees it in the hosted UI).

Show child attributes

createdAt

number | null

Unix epoch milliseconds.

updatedAt

number | null

Unix epoch milliseconds.

modelId

string | null

Model the study chats with.

systemPrompt

string | null

temperature

number | null

⌘I

Get a study

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/studies/{studyId} \
  --header 'Authorization: Bearer <token>'

import requests

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

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/studies/{studyId}', 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}/studies/{studyId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "name": "<string>",
  "serverCount": 123,
  "serverNames": [
    "<string>"
  ],
  "requireToolApproval": true,
  "servers": [
    {
      "id": "<string>",
      "name": "<string>",
      "useOAuth": true,
      "url": "<string>"
    }
  ],
  "environmentId": "<string>",
  "insights": {},
  "projectId": "<string>",
  "description": "<string>",
  "mode": "project_members",
  "hostStyle": "<string>",
  "hostId": "<string>",
  "hostName": "<string>",
  "link": {
    "path": "<string>",
    "url": "<string>"
  },
  "createdAt": 123,
  "updatedAt": 123,
  "modelId": "<string>",
  "systemPrompt": "<string>",
  "temperature": 123
}

API Guides

Endpoints

Get a study

Authorizations

Path Parameters

Response