---
title: "Create an MCP session token for a connection"
method: POST
path: "/api/v1/mcp/connections/{key_id}/tokens"
tags: ["MCP Configurations"]
---

# Create an MCP session token for a connection

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

## Request

- Base URL: `https://$SCALEKIT_ENVIRONMENT_URL`
- URL: `https://$SCALEKIT_ENVIRONMENT_URL/api/v1/mcp/connections/{key_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/connections/:key_id/tokens/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `key_id` string, required

## Request body

- McpServiceCreateMcpConnectionSessionTokenBody
  - `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: Token lifetime, between 60s and 24h. Defaults to 1h.
  - `identifier` string, required: Your app's ID for the user, the same value you used when the user connected.

## 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 - `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.
- `404`: Not found - no active connection with this name exists in the environment.

## Changes

- **2026-10-13** `a574bd9bbefd`: 1 info
  - added the new optional request property `access_level`
- **2026-10-04** `8895edb68754`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scalekit/apis/scalekit-api-reference/changes/api/v1/mcp/connections/:key_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)