Mint a session token

POST/api/v1/mcp/configs/{mcp_config_id}/tokens

Mints a short-lived JWT that represents a user identifier across the connected accounts associated with an MCP configuration. The supplied identifier becomes the token's sub claim; the token's aud claim is the MCP server URL bound to the configuration. Claims also carry the MCP configuration ID (mcp_cfg) and the list of resolved connected-account IDs (ca_ids). Use this operation to issue a single credential an MCP server can present on the user's behalf when calling provider tools. The mint fails if any connection mapped to the configuration has no active connected account for the identifier.

This page as markdown Virtual MCP servers overview

Authorization

Authorization: Bearer $TOKEN, an access token from the client credentials grant. See Authentication.

Path parameters

mcp_config_idstringrequired

Unique ID of the MCP configuration whose connections back the token. The configuration must exist in the caller's environment.

Body

identifierstringrequired

Your app's ID for the user, the same value you used when the user connected.

access_levelstring (enum)

Which tools the token can use: FULL (the default) or READ_ONLY, in capitals. A READ_ONLY token sees and calls only the server's read-only tools. See Limit an agent to read-only tools.

FULLREAD_ONLY

expirystring

How long the token lasts, in seconds with an s suffix, such as 1800s. Between 60s and 86400s (24 hours). Defaults to 3600s.

scalekit_client.actions.mcp.create_session_token

Create a short-lived session token for a user to access an MCP server. Pass exactly one of mcp_config_id or connection_name; the token works only on the MCP server of that target: mcp_config_id: the MCP configuration's server, at the config's mcp_server_url. It serves the tools the configuration exposes. connection_name: the connection's own MCP server, at <environment_url>/mcp/v3/connections/<connection_name>. It serves every tool of that connection, with no MCP configuration. Send the token as a Bearer token in the Authorization header when calling that URL.

scalekit_client.actions.mcp.create_session_token(
    mcp_config_id: str | None = None,
    identifier: str | None = None,
    expiry: timedelta | None = None,
    access_level: str | None = None,
    connection_name: str | None = None,
) -> CreateMcpSessionTokenResponse

Parameters

mcp_config_idstr | None

Scalekit ID of the MCP configuration the token grants access to, e.g. "cfg_01abc123".

identifierstr | None

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

expirytimedelta | None

Requested lifetime for the token as a Python timedelta. The server accepts 60 seconds to 24 hours and applies 1 hour when omitted. Fractions of a second are dropped. Example values: timedelta(minutes=30) — 30-minute token; timedelta(hours=8) — 8-hour token (work-day session); timedelta(days=1) — 24-hour token

access_levelstr | None

Tools the token can use. "READ_ONLY" limits it to tools annotated read-only: other tools are left out of the tool list and refused when called. "FULL", or omitting it, exposes every tool of the target. Values are case-sensitive.

connection_namestr | None

The connection name, as shown in AgentKit > Connections.

Returns CreateMcpSessionTokenResponse: The session token, a signed JWT, and expires_at, when it expires (UTC).

From scalekit-sdk-python 2.21.0.

scalekit.actions.mcp.createSessionToken

Mints a session token for one user, for either a Virtual MCP server or a connection's own MCP server. Set a target; if both are set, mcpConfigId is used: mcpConfigId: the token works on that configuration's config.mcpServerUrl (see getConfig). connectionName: the token works on the connection's own MCP server at <environment URL>/mcp/v3/connections/<connection name>, which exposes all of that connection's tools without an MCP configuration. The name is matched without regard to case, but the URL path is case-sensitive: build it from the connection's name exactly as stored. A token works only on the server it was minted for. The server URL is static; the token is what carries user identity. Mint a fresh one before every agent run and never reuse one across runs. Set the expiry longer than the run is expected to take. For a connection, the user should have an active connected account on it. When they do not, the server either rejects the call, or creates a pending connected account and returns a token whose tool calls report the account as not connected, depending on the environment.

scalekit.actions.mcp.createSessionToken(
  params: {
    identifier: string;
    expirySeconds?: number;
    accessLevel?: McpSessionTokenAccessLevel;
    mcpConfigId?: string;
    connectionName?: string;
  },
): Promise<CreateMcpSessionTokenResponse>

Parameters

identifierstringrequired

Your app's ID for the user, the same value you used when the user connected. Use a stable internal ID, not an email address.

expirySecondsnumber

Token lifetime in whole seconds, 60 to 86400. Defaults to 3600.

accessLevelMcpSessionTokenAccessLevel

Tools the token can use. Omit for 'FULL'.

mcpConfigIdstring

ID of the MCP configuration whose server the token is for.

connectionNamestring

The connection name, as shown in AgentKit > Connections.

Returns Promise<CreateMcpSessionTokenResponse>: The session token and its expiresAt time.

From @scalekit-sdk/node 2.20.0.

Response 200

expires_atstring

When the token expires: the time it was minted plus expiry.

tokenstring

The session token, a signed JWT. Its sub claim is the identifier and its aud claim is the MCP server URL it works at. Send it as Authorization: Bearer <token> from the MCP client.

Errors

Every error has the same body: code, message and details. See Errors and rate limits.

400Invalid request - mcp_config_id or identifier is missing or malformed, expiry is outside the 60s-24h window, the MCP configuration has no connections, or a connection has no active connected account for the supplied identifier

404Not Found - no MCP configuration exists with the supplied ID in the caller's environment

Used in

Request

curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs/cfg_85630864460904897/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "user_123",
    "expiry": "1800s"
  }'

from datetime import timedelta

result = scalekit_client.actions.mcp.create_session_token(
    mcp_config_id="cfg_85630864460904897",
    identifier="user_123",
    expiry=timedelta(seconds=1800),
)

const result = await scalekit.actions.mcp.createSessionToken({
  identifier: "user_123",
  expirySeconds: 1800,
  mcpConfigId: "cfg_85630864460904897",
});

Response 200

{
  "token": "[SESSION TOKEN]",
  "expires_at": "2026-10-02T15:00:00Z"
}