Server accounts

Upload tokens to a server account

Creates the account (201) or replaces its token in place (200, same id). A well-formed account id never creates one: an unknown id is 404. Any other reference is a name, and a name no account has creates the account.

Nothing checks who a token belongs to. The name is your own label, and replacing a token replaces it whoever it belongs to.

The account becomes hosted-only: hosted runs use it, and no local app, browser or sandbox ever receives its token. Tokens are used with the server URL saved in the project, so the body takes no URL. ID tokens are refused. Each token field is at most 16 KB.

Uploads to one server are budgeted per person: 60, refilling at 120 an hour. Past it the answer is 429 with Retry-After and details.retryAfterMs. On a server shared with the project, only project admins upload, and a member gets 403.

The answer is the account, never a token.

PUT

projects

{projectId}

servers

{serverId}

accounts

{account}

Upload tokens to a server account

curl --request PUT \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokens": {
    "access_token": "at_…",
    "expires_in": 3600
  },
  "clientInformation": {
    "clientId": "client_123"
  }
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account}"

payload = {
    "tokens": {
        "access_token": "at_…",
        "expires_in": 3600
    },
    "clientInformation": { "clientId": "client_123" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokens: {access_token: 'at_…', expires_in: 3600},
    clientInformation: {clientId: 'client_123'}
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account}', 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}/accounts/{account}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'tokens' => [
        'access_token' => 'at_…',
        'expires_in' => 3600
    ],
    'clientInformation' => [
        'clientId' => 'client_123'
    ]
  ]),
  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}/accounts/{account}"

	payload := strings.NewReader("{\n  \"tokens\": {\n    \"access_token\": \"at_…\",\n    \"expires_in\": 3600\n  },\n  \"clientInformation\": {\n    \"clientId\": \"client_123\"\n  }\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokens\": {\n    \"access_token\": \"at_…\",\n    \"expires_in\": 3600\n  },\n  \"clientInformation\": {\n    \"clientId\": \"client_123\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tokens\": {\n    \"access_token\": \"at_…\",\n    \"expires_in\": 3600\n  },\n  \"clientInformation\": {\n    \"clientId\": \"client_123\"\n  }\n}"

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

{
  "id": "acct_7f3a9c",
  "name": "test-automation-1",
  "kind": "personal",
  "isDefault": false,
  "needsReconnect": false,
  "hostedOnly": true,
  "expiresAt": 1781142000000,
  "createdAt": 1781138400000,
  "updatedAt": 1781138400000
}

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.

account

string

required

The account's id, or its name. A well-formed account id is matched as an id; anything else is a name, matched ignoring case.

Body

application/json

Tokens and the OAuth client they were issued to, and nothing else. A URL field (serverUrl, authorizationServerUrl, oauthResourceUrl) or tokens.id_token answers 400 with details.code: "field_not_accepted"; any other unknown field answers 400.

tokens

object

required

Show child attributes

clientInformation

object

required

Show child attributes

Response

The token was replaced; the account keeps its id.

One account a saved server signs in with. METADATA ONLY: no account response carries a token, a vault id, an email or any other recorded profile field.

string

required

Never changes, including while the account needs reconnecting. An eval suite's saved account choice stores it.

name

string | null

required

Your own label, or null for an account nobody named. Nothing checks it against who the token belongs to.

kind

enum<string>

required

project accounts belong to a server shared with the project; project admins manage them.

Available options:

personal,

project

isDefault

boolean

required

The effective default: the account marked as default, else the oldest. Runs with no saved account choice act as it.

needsReconnect

boolean

required

The issuer rejected a refresh, or the token expired with no refresh token stored. Upload a fresh token to restore it; the id stays.

hostedOnly

boolean

required

Hosted runs use the account, and no local app, browser or sandbox receives its token. True for accounts written by PUT .../accounts/{account} and for project accounts.

expiresAt

integer | null

required

When the access token expires, epoch milliseconds.

createdAt

integer

required

updatedAt

integer

required

⌘I

Upload tokens to a server account

curl --request PUT \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tokens": {
    "access_token": "at_…",
    "expires_in": 3600
  },
  "clientInformation": {
    "clientId": "client_123"
  }
}
'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account}"

payload = {
    "tokens": {
        "access_token": "at_…",
        "expires_in": 3600
    },
    "clientInformation": { "clientId": "client_123" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokens: {access_token: 'at_…', expires_in: 3600},
    clientInformation: {clientId: 'client_123'}
  })
};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account}', 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}/accounts/{account}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'tokens' => [
        'access_token' => 'at_…',
        'expires_in' => 3600
    ],
    'clientInformation' => [
        'clientId' => 'client_123'
    ]
  ]),
  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}/accounts/{account}"

	payload := strings.NewReader("{\n  \"tokens\": {\n    \"access_token\": \"at_…\",\n    \"expires_in\": 3600\n  },\n  \"clientInformation\": {\n    \"clientId\": \"client_123\"\n  }\n}")

	req, _ := http.NewRequest("PUT", 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.put("https://app.mcpjam.com/api/v1/projects/{projectId}/servers/{serverId}/accounts/{account}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokens\": {\n    \"access_token\": \"at_…\",\n    \"expires_in\": 3600\n  },\n  \"clientInformation\": {\n    \"clientId\": \"client_123\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tokens\": {\n    \"access_token\": \"at_…\",\n    \"expires_in\": 3600\n  },\n  \"clientInformation\": {\n    \"clientId\": \"client_123\"\n  }\n}"

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

{
  "id": "acct_7f3a9c",
  "name": "test-automation-1",
  "kind": "personal",
  "isDefault": false,
  "needsReconnect": false,
  "hostedOnly": true,
  "expiresAt": 1781142000000,
  "createdAt": 1781138400000,
  "updatedAt": 1781138400000
}

API Guides

Endpoints

Upload tokens to a server account

Authorizations

Path Parameters

Body

Response