Python SDK reference

scalekit_client.actions is the primary interface for AgentKit. It handles connected account management, MCP server provisioning, tool execution, and framework integrations.

Install and initialize

pip install scalekit-sdk-python

import os
from scalekit import ScalekitClient

scalekit_client = ScalekitClient(
    env_url=os.environ["SCALEKIT_ENV_URL"],
    client_id=os.environ["SCALEKIT_CLIENT_ID"],
    client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
)

actions = scalekit_client.actions

---

Actions client

Authentication

get_authorization_link

Generates a time-limited OAuth magic link to authorize a user’s connection.

Input schema

NameTypeRequiredDescription

identifierstroptionalUser identifier (e.g. email)

connection_namestroptionalConnector slug (e.g. gmail)

connected_account_idstroptionalDirect connected account ID (ca_...)

statestroptionalOpaque value passed through to the redirect URL

user_verify_urlstroptionalApp redirect URL for user verification

Response schema MagicLinkResponse

Field Type Description

link str OAuth magic link URL. Redirect the user here to start the authorization flow.

expiry datetime Link expiry timestamp

Example

magic_link = actions.get_authorization_link(
    identifier="user@example.com",
    connection_name="gmail",
    user_verify_url="https://your-app.com/verify",
)
# Redirect the user to magic_link.link

verify_connected_account_user

Verifies the user after OAuth callback. Call this from your redirect URL handler.

Input schema

NameTypeRequiredDescription

auth_request_idstrrequiredToken from the redirect URL query params

identifierstrrequiredCurrent user identifier

Response schema VerifyConnectedAccountUserResponse

Field Type Description

post_user_verify_redirect_url str URL to redirect the user to after successful verification

Example

result = actions.verify_connected_account_user(
    auth_request_id=request.args["auth_request_id"],
    identifier="user@example.com",
)
# Redirect to result.post_user_verify_redirect_url

---

Connected accounts

get_or_create_connected_account

Fetches an existing connected account or creates one if none exists. Use this as the default when setting up a user.

Input schema

NameTypeRequiredDescription

connection_namestrrequiredConnector slug

identifierstrrequiredUser's identifier

authorization_detailsdictoptionalOAuth token or static auth details

organization_idstroptionalOrganization tenant ID when your app scopes auth and accounts by org

user_idstroptionalYour application user ID when you map Scalekit accounts to internal users

api_configdictoptionalConnector-specific options (for example scopes or static auth fields)

Response schema CreateConnectedAccountResponse

Field Type Description

connected_account.id str Account ID (ca_...)

connected_account.identifier str User's identifier

connected_account.provider str Provider slug

connected_account.status str ACTIVE, INACTIVE, or PENDING

connected_account.authorization_type str OAuth, API_KEY, etc.

connected_account.token_expires_at datetime OAuth token expiry

Example

account = actions.get_or_create_connected_account(
    connection_name="gmail",
    identifier="user@example.com",
)
print(account.connected_account.id)

get_connected_account

Fetches auth details for a connected account. Returns sensitive credentials. Protect access to this method.

Use this when you know the connected account already exists and you need its credential payload. For first-time setup or general application flows, prefer get_or_create_connected_account so new users do not hit a not-found error.

Requires connected_account_id or connection_name + identifier.

Input schema

NameTypeRequiredDescription

connection_namestroptionalConnector slug. Use with identifier when you do not pass connected_account_id.

identifierstroptionalEnd-user or workspace identifier. Use with connection_name.

connected_account_idstroptionalConnected account ID (ca_...) when resolving by ID instead of name + identifier

Response schema GetConnectedAccountAuthResponse

Field Type Description

connected_account.id str Account ID (ca_...)

connected_account.identifier str User's identifier

connected_account.provider str Provider slug

connected_account.status str ACTIVE, INACTIVE, or PENDING

connected_account.authorization_type str OAuth, API_KEY, etc.

connected_account.authorization_details dict Credential payload (access token, API key, etc.)

connected_account.token_expires_at datetime OAuth token expiry

connected_account.last_used_at datetime Last time this account was used

connected_account.updated_at datetime Last update timestamp

list_connected_accounts

Input schema

NameTypeRequiredDescription

connection_namestroptionalFilter by connector

identifierstroptionalFilter by user identifier

providerstroptionalFilter by provider

Response schema ListConnectedAccountsResponse

Field Type Description

connected_accounts list List of ConnectedAccountForList objects (excludes authorization_details and api_config)

total_count int Total number of matching accounts

next_page_token str Token for the next page, if any

previous_page_token str Token for the previous page, if any

create_connected_account

Creates a connected account with explicit auth details.

Input schema

NameTypeRequiredDescription

connection_namestrrequiredConnector slug. Must match a connection configured in your environment.

identifierstrrequiredStable ID for this end user or workspace (email, user_id, or custom string)

authorization_detailsdictrequiredOAuth token payload, API key, or other credentials for this connector

organization_idstroptionalOrganization tenant ID when your app scopes auth and accounts by org

user_idstroptionalYour application user ID when you map Scalekit accounts to internal users

api_configdictoptionalConnector-specific options (for example scopes or static auth fields)

Returns CreateConnectedAccountResponse. Same shape as get_or_create_connected_account.

update_connected_account

Requires connected_account_id or connection_name + identifier.

Input schema

NameTypeRequiredDescription

connection_namestroptionalConnector slug. Use with identifier when you do not pass connected_account_id.

identifierstroptionalEnd-user or workspace identifier. Use with connection_name.

connected_account_idstroptionalConnected account ID (ca_...) when updating by ID instead of name + identifier

authorization_detailsdictoptionalReplace or merge stored credentials (OAuth tokens, API keys, etc.)

organization_idstroptionalOrganization tenant ID when your app scopes auth and accounts by org

user_idstroptionalYour application user ID when you map Scalekit accounts to internal users

api_configdictoptionalConnector-specific configuration to persist on the account

Returns UpdateConnectedAccountResponse.

delete_connected_account

Deletes a connected account and revokes its credentials. Requires connected_account_id or connection_name + identifier.

Input schema

NameTypeRequiredDescription

connection_namestroptionalConnector slug. Use with identifier when you do not pass connected_account_id.

identifierstroptionalEnd-user or workspace identifier. Use with connection_name.

connected_account_idstroptionalConnected account ID (ca_...) when deleting by ID instead of name + identifier

Returns DeleteConnectedAccountResponse.

---

Tool execution

execute_tool

Executes a named tool via Scalekit. Pre- and post-modifiers run automatically if registered.

Input schema

NameTypeRequiredDescription

tool_namestrrequiredTool name (e.g. gmail_fetch_emails)

tool_inputdictrequiredParameters the tool expects

identifierstroptionalUser's identifier

connected_account_idstroptionalDirect connected account ID

Response schema ExecuteToolResponse

Field Type Description

data dict Tool structured output

execution_id str Unique ID for this execution

Example

result = actions.execute_tool(
    tool_name="gmail_fetch_emails",
    tool_input={"max_results": 5, "label": "UNREAD"},
    identifier="user@example.com",
)
emails = result.data

---

Proxied API calls

request

Makes a REST API call on behalf of a connected account. Scalekit injects the user’s OAuth token automatically.

Input schema

NameTypeRequiredDescription

connection_namestrrequiredConnector slug

identifierstrrequiredUser's identifier

pathstrrequiredAPI path (e.g. /gmail/v1/users/me/messages)

methodstroptionalHTTP method. Default: GET

query_paramsdictoptionalURL query parameters appended to path

bodyanyoptionalJSON-serializable body for POST, PUT, PATCH, or similar methods

form_datadictoptionalMultipart form fields when the upstream API expects form data instead of JSON

headersdictoptionalExtra HTTP headers merged with Scalekit-injected auth headers

Returns requests.Response. Use .json(), .status_code, and standard response attributes.

Example

response = actions.request(
    connection_name="gmail",
    identifier="user@example.com",
    path="/gmail/v1/users/me/messages",
    query_params={"maxResults": 5, "q": "is:unread"},
)
messages = response.json()["messages"]

---

MCP server provisioning

actions.mcp manages Virtual MCP Servers. Any MCP-compatible agent framework (LangChain, Google ADK, Anthropic, OpenAI, and others) can connect to these servers directly.

Two-step model: Create a config once (defines which connectors and tools to expose) to get a static Virtual MCP Server URL. Before each agent run, mint a short-lived session token to authenticate the user.

Configs

actions.mcp.create_config

Input schema

NameTypeRequiredDescription

namestrrequiredConfig name

descriptionstroptionalHuman-readable summary of what this MCP config exposes

connection_tool_mappingslistoptionalList of McpConfigConnectionToolMapping objects

Response schema CreateMcpConfigResponse

Field Type Description

config.id str Config ID

config.name str Config name

config.connection_tool_mappings list Connector-to-tools mappings

Example

from scalekit.actions.models.mcp_config import McpConfigConnectionToolMapping

config = actions.mcp.create_config(
    name="email-agent",
    connection_tool_mappings=[
        McpConfigConnectionToolMapping(
            connection_name="gmail",
            tools=["gmail_fetch_emails", "gmail_send_email"],
        )
    ],
)

actions.mcp.list_configs

Input schema

NameTypeRequiredDescription

page_sizeintoptionalMaximum configs per page (server default if omitted)

page_tokenstroptionalOpaque cursor from a previous list response

filter_namestroptionalFilter by exact name

filter_providerstroptionalFilter by provider slug

searchstroptionalFree-text search on name

Returns ListMcpConfigsResponse.

actions.mcp.update_config

Input schema

NameTypeRequiredDescription

config_idstrrequiredMCP config ID from create_config or list_configs

descriptionstroptionalNew human-readable description for this config

connection_tool_mappingslistoptionalReplaces existing mappings

Returns UpdateMcpConfigResponse.

actions.mcp.delete_config

Input schema

NameTypeRequiredDescription

config_idstrrequiredMCP config ID to delete

Returns DeleteMcpConfigResponse.

Session tokens

actions.mcp.list_mcp_connected_accounts

Returns the connection status for each connector configured in a Virtual MCP Server, for a specific user. Call this before minting a session token to verify all connections are ACTIVE.

Input schema

NameTypeRequiredDescription

config_idstrrequiredVirtual MCP Server config ID from list_configs or create_config

identifierstrrequiredUser identifier

Response schema ListMcpConnectedAccountsResponse

Field Type Description

connected_accounts list One entry per connector configured in the Virtual MCP Server

connected_accounts[].connection_name str Connector slug

connected_accounts[].connected_account_status str ACTIVE, PENDING, EXPIRED, REVOKED, or ERROR

Example

accounts_response = scalekit_client.actions.mcp.list_mcp_connected_accounts(
    config_id=mcp_id,
    identifier="user@example.com",
)
for account in accounts_response.connected_accounts:
    if account.connected_account_status != "ACTIVE":
        print(f"{account.connection_name} is not active — prompt user to authorize")

actions.mcp.create_session_token

Mints a short-lived session token scoped to a user and a Virtual MCP Server config. Pass the token as a bearer auth header when connecting to the MCP server. Mint a fresh token before each agent run.

Input schema

NameTypeRequiredDescription

mcp_config_idstrrequiredVirtual MCP Server config ID

identifierstrrequiredUser identifier

expirytimedeltaoptionalToken lifetime (default: 1 hour). Set longer than the expected agent run duration.

Response schema CreateMcpSessionTokenResponse

Field Type Description

token str Bearer token to pass as Authorization header

Example

from datetime import timedelta

token_response = scalekit_client.actions.mcp.create_session_token(
    mcp_config_id=mcp_id,
    identifier="user@example.com",
    expiry=timedelta(hours=1),
)
token = token_response.token
# Pass as: {"Authorization": f"Bearer {token}"}

---

Framework adapters

Pre-built integrations for LangChain and Google ADK. Use these when your agent runs in one of these frameworks and you prefer native tool objects over an MCP URL.

MCP is the recommended path

Virtual MCP Servers expose a static URL compatible with any MCP-supporting framework. Use framework adapters only when native tool objects are required.

LangChain

pip install langchain

actions.langchain.get_tools

Input schema

NameTypeRequiredDescription

identifierstrrequiredUser connected account identifier

providerslistoptionalFilter by provider (e.g. ["google"])

tool_nameslistoptionalFilter by tool name

connection_nameslistoptionalFilter by connection name

page_sizeintoptionalMaximum tools per page. Use 100 for discovery so connectors with more than the default page are not truncated.

page_tokenstroptionalOpaque cursor from a previous list response

Response schema List[StructuredTool]

Field Type Description

[].name str Tool name

[].description str Tool description

[].args_schema object Pydantic schema for the tool inputs

Example

from langchain.agents import create_react_agent

tools = actions.langchain.get_tools(
    identifier="user@example.com",
    page_size=100,  # avoid missing tools when a connector has more than the default page
)
agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)

Google ADK

pip install google-adk

actions.google.get_tools

Same parameters as actions.langchain.get_tools.

Returns List[ScalekitGoogleAdkTool]. Pass it directly to a Google ADK agent.

Example

tools = actions.google.get_tools(
    identifier="user@example.com",
    page_size=100,  # avoid missing tools when a connector has more than the default page
)

---

Tools client

scalekit_client.actions.tools gives access to raw tool schemas. Use this when building a custom adapter or passing schemas directly to an LLM API (e.g. Anthropic, OpenAI).

actions.tools.list_tools

Input schema

NameTypeRequiredDescription

filterFilteroptionalFilter by provider, identifier, or tool name

page_sizeintoptionalMaximum tools per page. Use 100 for discovery so connectors with more than the default page are not truncated.

page_tokenstroptionalOpaque cursor from a previous list response

Response schema ListToolsResponse

Field Type Description

tools list List of tool schemas (name, description, input schema)

next_page_token str Token for the next page, if any

actions.tools.list_scoped_tools

Lists tools scoped to a specific user. Use this method for tool discovery because it returns pagination metadata such as next_page_token and total_size; framework get_tools() helpers return framework-ready tool objects and do not expose that metadata.

Input schema

NameTypeRequiredDescription

identifierstrrequiredUser connected account identifier

filterScopedToolFilteroptionalFilter by providers, tool names, or connection names

page_sizeintoptionalMaximum tools per page. Use 100 for discovery so connectors with more than the default page are not truncated.

page_tokenstroptionalOpaque cursor from a previous list response

Response schema ListScopedToolsResponse

Field Type Description

tools list List of tool schemas (name, description, input_schema)

tools[].name str Tool name

tools[].description str Tool description

tools[].input_schema object JSON Schema for tool inputs. Pass directly to LLM API.

next_page_token str Token for the next page, if any

Example

tools_response = scalekit_client.actions.tools.list_scoped_tools(
    identifier="user@example.com",
    page_size=100,
)
# Pass tools_response.tools to your LLM's tool call API

actions.tools.execute_tool

Low-level tool execution. Bypasses modifiers. Prefer actions.execute_tool in most cases.

Input schema

NameTypeRequiredDescription

tool_namestrrequiredRegistered tool name to execute

identifierstrrequiredEnd-user or workspace identifier used to resolve the connected account

paramsdictoptionalTool arguments matching the tool input schema

connected_account_idstroptionalConnected account ID (ca_...) when you already know it

Returns ExecuteToolResponse. Same shape as actions.execute_tool.

---

Modifiers

Modifiers intercept tool calls to transform inputs or outputs, useful for validation, enrichment, or logging.

@actions.pre_modifier(tool_names=["gmail_fetch_emails"])
def add_default_label(tool_input):
    tool_input.setdefault("label", "UNREAD")
    return tool_input

@actions.post_modifier(tool_names=["gmail_fetch_emails"])
def filter_attachments(tool_output):
    tool_output["emails"] = [e for e in tool_output["emails"] if not e.get("has_attachment")]
    return tool_output

Decorator	Receives	Returns
@actions.pre_modifier(tool_names)	dict	Modified dict
@actions.post_modifier(tool_names)	dict	Modified dict

tool_names accepts a string or a list of strings. Multiple modifiers for the same tool chain in registration order.

---

Error handling

from scalekit.common.exceptions import ScalekitNotFoundException, ScalekitServerException

try:
    account = actions.get_connected_account(
        connection_name="gmail",
        identifier="user@example.com",
    )
except ScalekitNotFoundException:
    # Account does not exist: create it or redirect to auth
    pass
except ScalekitServerException as e:
    print(e.error_code, e.http_status)

Exception	When raised
ScalekitNotFoundException	Resource not found
ScalekitUnauthorizedException	Invalid credentials
ScalekitForbiddenException	Insufficient permissions
ScalekitServerException	Base class for all server errors