Directory readiness

Start an OpenAI plugin-directory readiness run

Grades the saved server against OpenAI’s plugin-directory requirements and returns 202 with a run id. submissionMode is required and never inferred: inferring it would read a forgotten package as mcp-only and report the package lane not-applicable, turning a missing input into a clean bill of health. Hosted runs grade the two wire-safe shapes; the package shapes need an upload this API cannot receive and are available from the CLI.

POST

projects

{projectId}

servers

{serverId}

readiness-runs

openai

Start an OpenAI plugin-directory readiness run

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "<string>",
  "includeLlmObservations": false
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai"

payload = {
    "idempotencyKey": "<string>",
    "includeLlmObservations": False
}
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>', includeLlmObservations: false})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai', 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}/servers/{serverId}/readiness-runs/openai",
  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>',
    'includeLlmObservations' => false
  ]),
  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}/servers/{serverId}/readiness-runs/openai"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"includeLlmObservations\": false\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}/servers/{serverId}/readiness-runs/openai")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"includeLlmObservations\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai")

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  \"includeLlmObservations\": false\n}"

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

{
  "runId": "<string>",
  "projectId": "<string>",
  "serverId": "<string>",
  "readinessKind": "claude",
  "status": "pending",
  "deduped": true,
  "includeLlmObservations": true
}

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.

serverId

string

required

ID of the server inside the project.

Body

application/json

submissionMode

enum<string>

required

The declared submission shape.

Available options:

mcp-only,

mcp-imported-skills

idempotencyKey

string

Deduplicates a retried POST. More load-bearing here than usual: a readiness run dials a third party's server, and a retried start that created a second run would do that twice.

Maximum string length: 200

includeLlmObservations

boolean

default:false

Add model-backed experience observations. Consumes MCPJam credits. Off by default, and deliberately: a billed opt-in that defaulted on would start charging every existing caller on the day it shipped. Observations are non-dispositive and can never make a server not-ready; a refused reservation makes no provider call and completes the run with llmObservations.reason set to billing_limit_reached.

Response

The run was accepted and is executing.

The 202 receipt. Poll the run detail; do not re-POST.

runId

string

required

projectId

string

required

serverId

string

required

readinessKind

enum<string>

required

Available options:

claude,

openai

status

enum<string>

required

The run's status when the start returned. pending for a fresh start; for a deduped start, whatever the existing run is already at — which may be completed, because a replayed idempotency key can name a run that finished long ago.

Available options:

pending,

running,

completed,

failed,

cancelled

deduped

boolean

required

This request replayed an existing run rather than starting one.

includeLlmObservations

boolean

required

⌘I

Start an OpenAI plugin-directory readiness run

curl --request POST \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "<string>",
  "includeLlmObservations": false
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai"

payload = {
    "idempotencyKey": "<string>",
    "includeLlmObservations": False
}
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>', includeLlmObservations: false})
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai', 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}/servers/{serverId}/readiness-runs/openai",
  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>',
    'includeLlmObservations' => false
  ]),
  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}/servers/{serverId}/readiness-runs/openai"

	payload := strings.NewReader("{\n  \"idempotencyKey\": \"<string>\",\n  \"includeLlmObservations\": false\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}/servers/{serverId}/readiness-runs/openai")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"idempotencyKey\": \"<string>\",\n  \"includeLlmObservations\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/readiness-runs/openai")

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  \"includeLlmObservations\": false\n}"

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

{
  "runId": "<string>",
  "projectId": "<string>",
  "serverId": "<string>",
  "readinessKind": "claude",
  "status": "pending",
  "deduped": true,
  "includeLlmObservations": true
}

API Guides

Endpoints

Start an OpenAI plugin-directory readiness run

Authorizations

Path Parameters

Body

Response