Migrate from Composio to Scalekit

This guide maps Composio concepts to their Scalekit AgentKit equivalents and walks through each migration step: SDK setup, authentication, tool execution, and MCP. Use it as a reference while porting your agent code.

1. Create a Scalekit account

   Sign up at app.scalekit.com and copy your API credentials from Dashboard > Developers > Settings > API Credentials.

2. Set environment variables

   SCALEKIT_CLIENT_ID=your_client_id
   SCALEKIT_CLIENT_SECRET=your_client_secret
   SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com

3. Install the SDK

   • Python
   • Node.js

   pip install scalekit-sdk-python

4. Initialize the client

   Scalekit uses a single client instance. There is no session object — you pass identifier on each API call.

   • Python
   • Node.js

   import os
   import scalekit.client
   
   scalekit_client = scalekit.client.ScalekitClient(
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
   )
   actions = scalekit_client.actions

In Composio, auth configs are created programmatically or via the dashboard. In Scalekit, you configure connections in the dashboard.

For each Composio toolkit your agent uses (Gmail, Slack, GitHub, etc.), create a corresponding connection in Dashboard > AgentKit > Connections > Add connection. See Configure a connection for the full walkthrough.

Both platforms create per-user records (connected accounts) and generate OAuth links. The SDK methods differ.

# Composio handles auth in-chat or via connect link
session = composio.create(user_id="user_123")
# Auth is triggered automatically when a tool requires it

# Create or retrieve the connected account
response = actions.get_or_create_connected_account(
    connection_name="gmail",
    identifier="user_123",
)
connected_account = response.connected_account

# Generate an authorization link if the account is not yet active
if connected_account.status != "ACTIVE":
    link_response = actions.get_authorization_link(
        connection_name="gmail",
        identifier="user_123",
    )
    auth_url = link_response.link
    # Redirect or send auth_url to the user

// Composio handles auth in-chat or via connect link
const session = await composio.create("user_123");
// Auth is triggered automatically when a tool requires it

1
import { ConnectorStatus } from '@scalekit-sdk/node';
2

3
// Create or retrieve the connected account
4
const response = await scalekit.actions.getOrCreateConnectedAccount({
5
  connectionName: 'gmail',
6
  identifier: 'user_123',
7
});
8

9
const connectedAccount = response.connectedAccount;
10

11
// Generate an authorization link if the account is not yet active
12
if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
13
  const linkResponse = await scalekit.actions.getAuthorizationLink({
14
    connectionName: 'gmail',
15
    identifier: 'user_123',
16
  });
17
  const authUrl = linkResponse.link;
18
  // Redirect or send authUrl to the user
19
}

Key difference: Composio can trigger auth in-chat automatically. With Scalekit, your app explicitly creates the connected account and sends the authorization link to the user. Once the user completes the OAuth flow, the connected account becomes ACTIVE and your agent can execute tools.

Composio tracks two statuses (ACTIVE and INACTIVE). Scalekit uses more granular states:

Check status before executing tools. If the account is not ACTIVE, generate a new authorization link.

session = composio.create(user_id="user_123")
tools = session.tools()  # all tools the user is authorized for

tools_response, _ = scalekit_client.actions.tools.list_scoped_tools(
    identifier="user_123",
    # Required: list every connection whose tools the agent should see
    filter={"connection_names": ["gmail"]},
    page_size=100,
)

const session = await composio.create("user_123");
const tools = await session.tools();  // all tools the user is authorized for

const { tools } = await scalekit.tools.listScopedTools('user_123', {
  // Required: list every connection whose tools the agent should see
  filter: { connectionNames: ['gmail'] },
  pageSize: 100,
});

session = composio.create(user_id="user_123")
tools = session.tools()
# Framework handles execution via the agent loop, or:
# composio.tools.execute(tool_name="GMAIL_FETCH_MAILS", params={...})

result = actions.execute_tool(
    tool_name="gmail_fetch_mails",
    identifier="user_123",
    connection_name="gmail",
    tool_input={"query": "is:unread", "max_results": 5},
)
print(result.data)

const session = await composio.create("user_123");
const tools = await session.tools();
// Framework handles execution via the agent loop

const result = await scalekit.actions.executeTool({
  toolName: 'gmail_fetch_mails',
  identifier: 'user_123',
  connector: 'gmail',
  toolInput: { query: 'is:unread', max_results: 5 },
});
console.log(result.data);

Key differences:

• Composio tool names are uppercase (GMAIL_FETCH_MAILS); Scalekit uses lowercase (gmail_fetch_mails)
• Composio’s session model means you don’t pass user_id on each call. With Scalekit, pass identifier and the connection name on every executeTool call: connection_name in Python, connector in Node.js
• Both return structured, LLM-ready output

Composio and Scalekit may name tools differently for the same connector. Browse the connector’s tool list in the Scalekit connector catalog to find the exact tool names. Common patterns:

Tool input schemas may also differ. Check each tool’s parameters in the connector catalog and update your agent’s tool input accordingly.

Both platforms support MCP (Model Context Protocol) for framework-agnostic tool discovery and execution.

Before (Composio):

{
  "mcpServers": {
    "composio": {
      "url": "https://backend.composio.dev/v3/mcp/{SERVER_ID}?user_id={USER_ID}",
      "headers": {
        "x-api-key": "<COMPOSIO_API_KEY>"
      }
    }
  }
}

After (Scalekit):

Scalekit MCP uses Virtual MCP servers:

1. Create a Virtual MCP server — define which connections and tools the server exposes (one-time). This gives you a static mcp_server_url.
2. Mint a session token — before each agent run, call create_session_token for the user. Pass it as a bearer auth header.

See Virtual MCP servers for the full setup.

{
  "mcpServers": {
    "scalekit": {
      "url": "<MCP_SERVER_URL>",
      "headers": {
        "Authorization": "Bearer <SESSION_TOKEN>"
      }
    }
  }
}

Key difference: Composio embeds the user ID in the URL. Scalekit uses a static server URL shared across all users, with a short-lived session token per agent run for authentication.

In Scalekit, custom tools use API Proxy mode (actions.request). The proxy is available out of the box for every connector with no extra configuration. You define the tool contract in your application code and call the provider’s REST endpoint through Scalekit, which injects the user’s credentials automatically.

response = actions.request(
    connection_name="gmail",
    identifier="user_123",
    method="GET",
    path="/gmail/v1/users/me/messages",
)

const response = await scalekit.actions.request({
  connectionName: 'gmail',
  identifier: 'user_123',
  method: 'GET',
  path: '/gmail/v1/users/me/messages',
});

If your agent connects to an API or MCP server that isn’t in Scalekit’s built-in catalog, you can add your own connector. Custom connectors support OAuth 2.0, API keys, bearer tokens, and other auth types. Once created, they work exactly like built-in connectors — same connected account flow, same actions.request() proxy, same MCP tool calling.

See Add your own connector for the full walkthrough.

• Scalekit account created, API credentials saved as environment variables
• Scalekit SDK installed
• Connections created in the Scalekit Dashboard for each connector
• Connected account creation and authorization link flow ported
• Tool names updated from uppercase to lowercase
• executeTool calls updated with identifier and the connection name (connection_name in Python, connector in Node.js)
• Tool input schemas verified against the Scalekit connector catalog
• Virtual MCP server created and session token flow implemented (if using MCP)
• Custom tools ported to actions.request() (if applicable)
• Agent tested end-to-end with a test user
• Users re-authorized through Scalekit’s OAuth flow