Mint a session token for a connection

POST/api/v1/mcp/connections/{key_id}/tokens

Mints a short-lived token for one user that an MCP client sends to one connection's MCP server, at <environment URL>/mcp/v3/connections/{key_id}, without a Virtual MCP server. The token's sub claim is the identifier and its aud claim is that server URL, so the token works only there. Use it when an agent needs the tools of exactly one connection.

This page as markdown Virtual MCP servers overview

Authorization

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

Path parameters

key_idstringrequired

The connection name, as shown in AgentKit > Connections. It's also the last path segment of the connection's MCP server URL.

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 - key_id or identifier is missing or malformed, expiry is outside the 60s-24h window, access_level isn't FULL or READ_ONLY, the connection isn't an AgentKit connection, or the user has no active account on the connection. Depending on the environment, Scalekit instead creates a pending account for the user and returns a token, so the user can authorize from the MCP client.

404Not found - no active connection with this name exists in the environment.

Used in

Request

curl -sS -X POST \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/connections/gmail/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(
    identifier="user_123",
    expiry=timedelta(seconds=1800),
    connection_name="gmail",
)

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

Response 200

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