composio-skills-reference/composio-sdk/rules/tr-session-basic.md

title, impact, description, tags

title	impact	description	tags
Create Basic Tool Router Sessions	HIGH	Essential pattern for initializing Tool Router sessions with proper user isolation	tool-router session initialization agents

Create Basic Tool Router Sessions

Always create isolated Tool Router sessions per user to ensure proper data isolation and scoped tool access.

❌ Incorrect

// DON'T: Using shared session for multiple users
const sharedSession = await composio.create('default', {
  toolkits: ['gmail']
});
// All users share the same session - security risk!

# DON'T: Using shared session for multiple users
shared_session = composio.tool_router.create(
    user_id="default",
    toolkits=["gmail"]
)
# All users share the same session - security risk!

✅ Correct

// DO: Create per-user sessions for isolation
import { Composio } from '@composio/core';

const composio = new Composio();

// Each user gets their own isolated session
const session = await composio.create('user_123', {
  toolkits: ['gmail', 'slack']
});

console.log('Session ID:', session.sessionId);
console.log('MCP URL:', session.mcp.url);

# DO: Create per-user sessions for isolation
from composio import Composio

composio = Composio()

# Each user gets their own isolated session
session = composio.tool_router.create(
    user_id="user_123",
    toolkits=["gmail", "slack"]
)

print(f"Session ID: {session.session_id}")
print(f"MCP URL: {session.mcp.url}")

Key Points

• User Isolation: Each user must have their own session
• Toolkit Scoping: Specify which toolkits the session can access
• Session ID: Store the session ID to retrieve it later
• MCP URL: Use this URL with any MCP-compatible AI framework

Reference

• Tool Router API Docs
• Creating Sessions