Composio Sessions: Per-User Agent Runtime Context

A session is the central primitive in Composio. It binds a user ID to a runtime context that contains tool access, authentication state, an MCP endpoint, and execution logs. Every tool call, connected account lookup, and workbench operation runs inside this scoped context — keeping one user’s data cleanly isolated from another’s.

Creating a session

Pass your user ID to composio.create() to open a new session. Every call returns a fresh session ID. Use the same session ID across turns of a conversation to preserve tool and workbench state.

Tab Title
Tab Title

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });

const session = await composio.create("user_123");

from composio import Composio

composio = Composio(api_key="your_api_key")

session = composio.create(user_id="user_123")

To resume an existing session in a later turn, use composio.use() instead of create():

Tab Title
Tab Title

const session = await composio.use("existing_session_id");
const tools = await session.tools();

session = composio.use("existing_session_id")
tools = session.tools()

Getting tools from a session

Call session.tools() to retrieve provider-wrapped tools ready to pass into your AI framework. By default, this returns the session’s meta tools (COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS, etc.) plus any preloaded tools you configured.

Tab Title
Tab Title

// Default: meta tools only
const tools = await session.tools();

// Preload specific tools at session creation
const session = await composio.create("user_123", {
  toolkits: ["gmail", "github"],
  preload: {
    tools: ["GMAIL_FETCH_EMAILS", "GITHUB_CREATE_ISSUE"],
  },
});

const tools = await session.tools();
// Returns preloaded tools + meta tools

# Default: meta tools only
tools = session.tools()

# Preload specific tools at session creation
session = composio.create(
    user_id="user_123",
    toolkits=["gmail", "github"],
    preload={
        "tools": ["GMAIL_FETCH_EMAILS", "GITHUB_CREATE_ISSUE"],
    },
)

tools = session.tools()
# Returns preloaded tools + meta tools

You can also restrict the session to a specific set of toolkits to limit what the agent can discover:

Tab Title
Tab Title

const session = await composio.create("user_123", {
  toolkits: ["gmail", "slack"],
});

session = composio.create(
    user_id="user_123",
    toolkits=["gmail", "slack"],
)

Keep preloaded tool sets small (fewer than 20 tools) to avoid bloating the model’s context window. Let the agent use COMPOSIO_SEARCH_TOOLS to discover additional tools at runtime.

Session MCP endpoint

Every session exposes a remote MCP server. Any MCP-compatible client — Claude Desktop, Cursor, or your own MCP client — can connect to it using the session URL and your API key as the auth header.

Tab Title
Tab Title

const session = await composio.create("user_123");

const mcpUrl = session.mcp.url;
const mcpHeaders = session.mcp.headers;

console.log(mcpUrl);
// e.g. https://mcp.composio.dev/session/sess_abc123
console.log(mcpHeaders);
// { Authorization: "Bearer <your_api_key>" }

session = composio.create(user_id="user_123")

mcp_url = session.mcp.url
mcp_headers = session.mcp.headers

print(mcp_url)
# e.g. https://mcp.composio.dev/session/sess_abc123
print(mcp_headers)
# { "Authorization": "Bearer <your_api_key>" }

Pass mcp_url and mcp_headers to any MCP client — both url and native tools point at the same session context, so tool calls, auth, and workbench state are shared regardless of which access method you use.

See MCP guide for provider-specific setup instructions (Claude Desktop, Cursor, Vercel AI SDK, etc.).

Generating a connect link from a session

Use session.authorize() when you want to authenticate a user to a toolkit programmatically — for example, during onboarding or from a settings page.

Tab Title
Tab Title

const connectionRequest = await session.authorize("github", {
  callbackUrl: "https://myapp.com/callback",
});

console.log(connectionRequest.redirectUrl);
// Send this URL to the user

const connectedAccount = await connectionRequest.waitForConnection();
console.log(connectedAccount.status); // "ACTIVE"

connection_request = session.authorize("github")

print(connection_request.redirect_url)
# Send this URL to the user

connected_account = connection_request.wait_for_connection()
print(connected_account.status)  # "ACTIVE"

User IDs

User IDs are arbitrary strings you define. Composio stores connected accounts and tool-execution history under this ID, so consistent, unique IDs are essential.

Practice	Recommendation
Recommended	Database UUID or primary key (`user.id`)
Acceptable	Unique username (`user.username`)
Avoid	Email addresses — they can change and may be reassigned
Never in production	`"default"` — routes all users to the same connected accounts

Using "default" as a user ID in production means every user shares the same connected accounts. This is a serious data-isolation issue. Use a stable, unique identifier from your database instead.

A single user ID can have multiple connected accounts for the same toolkit (for example, a work Gmail and a personal Gmail). To specify which account to use in a session, pass it via connectedAccounts:

Tab Title
Tab Title

const session = await composio.create("user_123", {
  connectedAccounts: {
    gmail: ["ca_work_gmail"],
    github: ["ca_personal_github"],
  },
});

session = composio.create(
    user_id="user_123",
    connected_accounts={
        "gmail": ["ca_work_gmail"],
        "github": ["ca_personal_github"],
    },
)

Session vs. direct access

Sessions and the direct composio.tools.get() method serve different needs:

	Session (`composio.create()`)	Direct (`composio.tools.get()`)
Scope	Scoped to a single user ID	Any user ID you pass per call
Meta tools	Included by default	Not included
MCP endpoint	Provided via `session.mcp`	Not available
Workbench	Included by default	Not available
Auth flow	Managed by `COMPOSIO_MANAGE_CONNECTIONS`	Manual via `connectedAccounts.link()`
Best for	Agentic chat and multi-turn conversations	Direct tool execution, scripting, batch jobs

Use sessions for any agentic or conversational flow. Use composio.tools.get() when you want to call a specific tool directly without the session overhead.

Authentication

Auth configs, Connect Links, and OAuth token management

Connected Accounts

Listing, creating, and managing per-user credentials

Tools & Toolkits

Discovering, filtering, and executing tools directly

MCP Guide

Connecting MCP clients to a Composio session

Get Started

Core Concepts

Guides

Providers

CLI

Composio Sessions: Per-User Agent Runtime Context

Creating a session

Getting tools from a session

Session MCP endpoint

Generating a connect link from a session

User IDs

Session vs. direct access

Authentication

Connected Accounts

Tools & Toolkits

MCP Guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Providers

CLI

Documentation Index

​Creating a session

​Getting tools from a session

​Session MCP endpoint

​Generating a connect link from a session

​User IDs

​Session vs. direct access

Authentication

Connected Accounts

Tools & Toolkits

MCP Guide

Build docs developers (and LLMs) love

Creating a session

Getting tools from a session

Session MCP endpoint

Generating a connect link from a session

User IDs

Session vs. direct access