---
title: "Create an MCP session token"
method: POST
path: "/api/v1/mcp/configs/{mcp_config_id}/tokens"
tags: ["MCP Configurations"]
---

# Create an MCP session token

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

## Request

- Base URL: `https://$SCALEKIT_ENVIRONMENT_URL`
- URL: `https://$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/configs/{mcp_config_id}/tokens`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://$SCALEKIT_ENVIRONMENT_URL/oauth/token`
- TypeScript: <https://skmtc.dev/scalekit/apis/scalekit-api-reference/docs/api/v1/mcp/configs/:mcp_config_id/tokens/post.ts> (a function with typed inputs; its response is checked against the schema)

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. For a `META` server, the user needn't have connected accounts yet.

## Path parameters

- `mcp_config_id` string, required

## Request body

- McpServiceCreateMcpSessionTokenBody
  - `access_level` 'FULL' | 'READ_ONLY': Which tools the token can use. `READ_ONLY` limits it to the server's read-only tools; other tools are left out of `tools/list` and refused when called. `FULL`, or omitting the field, gives every tool the server serves. Case-sensitive.
  - `expiry` string: Optional token lifetime. Must be between 60s and 24h. Defaults to 1h when omitted.
  - `identifier` string, required: Upstream-provider identifier (typically the user's email or provider user-id) shared by the connected accounts the token represents. A single identifier can map to one connected account per connection in the MCP configuration.

## Response `200`

Token created successfully; returns the signed JWT and its absolute expiry

- McpCreateMcpSessionTokenResponse
  - `expires_at` string, date-time: Absolute time at which the token expires. Equals issued_at + expiry.
  - `token` string: Signed JWT (RS256) whose `sub` claim is the supplied identifier and whose `aud` claim is the MCP server URL the token is scoped to: the MCP configuration's server URL for a configuration token, or the connection's `<env_url>/mcp/v3/connections/{key_id}` URL for a connection token. A configuration token also carries the MCP configuration ID (`mcp_cfg`); a connection token carries the connection ID (`conn_id`) instead. Both carry the resolved connected-account IDs (`ca_ids`). Signed with the calling environment's active JWT signing key.

## Other responses

- `400`: Invalid 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
- `404`: Not Found - no MCP configuration exists with the supplied ID in the caller's environment

## Changes

- **2026-10-13** `a574bd9bbefd`: 1 info
  - added the new optional request property `access_level`
- **2026-07-13** `371b89eb40a0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scalekit/apis/scalekit-api-reference/changes/api/v1/mcp/configs/:mcp_config_id/tokens/post.md)

---

[API](https://skmtc.dev/scalekit/apis/scalekit-api-reference.md) - [All operations](https://skmtc.dev/scalekit/apis/scalekit-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/scalekit/apis/scalekit-api-reference/revisions/f47f1022d844?raw)