Composio now introduces comprehensive MCP (Model Control Protocol) support and an experimental ToolRouter for creating isolated, scoped sessions with advanced toolkit management. These features enable seamless integration with modern AI frameworks and provide powerful session-based tool routing capabilities.

Why Use MCP & ToolRouter?

Framework Integration: Native MCP support for Vercel AI, Mastra, OpenAI Agents, and LangChain
Session Isolation: Create isolated sessions with specific toolkit configurations
Advanced Authentication: Flexible auth config management per toolkit
Scoped Access: Control which tools are available within each session
Multi-Service Workflows: Route tool calls efficiently across different services
Development & Testing: Perfect for testing and development with scoped MCP server access

TypeScript SDK (v0.1.53)

Added: MCP API

Core MCP Features:

MCP Server Creation: Create and manage MCP server configurations
User-Specific URLs: Generate unique MCP server URLs for individual users
Toolkit Configuration: Support for multiple toolkits with custom auth configs
Tool Filtering: Specify allowed tools per configuration
Connection Management: Choose between manual and automatic account management

Basic Usage:

1 import { Composio } from '@composio/core';
2 
3 const composio = new Composio({
4   apiKey: process.env.COMPOSIO_API_KEY,
5 });
6 
7 // Create MCP configuration
8 const mcpConfig = await composio.mcp.create('my-server-name', {
9   toolkits: [
10     { toolkit: 'github', authConfigId: 'ac_233434343' },
11     { toolkit: 'gmail', authConfigId: 'ac_567890123' }
12   ],
13   allowedTools: ['GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL'],
14   manuallyManageConnections: false,
15 });
16 
17 // Generate server instance for a user
18 const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);
19 console.log('MCP URL:', serverInstance.url);

Framework Integration Examples:

1 // Vercel AI Integration
2 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
3 import { experimental_createMCPClient as createMCPClient } from 'ai';
4 
5 const mcpClient = await createMCPClient({
6   name: 'composio-mcp-client',
7   transport: new SSEClientTransport(new URL(serverInstance.url)),
8 });
9 
10 // Mastra Integration
11 import { MCPClient as MastraMCPClient } from '@mastra/mcp';
12 
13 const mcpClient = new MastraMCPClient({
14   servers: {
15     composio: { url: new URL(mcpSession.url) },
16   },
17 });
18 
19 // OpenAI Agents Integration
20 import { hostedMcpTool } from '@openai/agents';
21 
22 const tools = [
23   hostedMcpTool({
24     serverLabel: 'composio',
25     serverUrl: mcpSession.url,
26   }),
27 ];

Added: Experimental ToolRouter

Core ToolRouter Features:

Session-Based Routing: Create isolated sessions for specific users and toolkit combinations
Dynamic Configuration: Configure toolkits and auth configs per session
MCP Server URLs: Each session gets a unique MCP server endpoint
Flexible Toolkit Management: Support for string names or detailed toolkit configurations
Connection Control: Manual or automatic connection management per session

Basic Usage:

1 // Create session with simple toolkit names
2 const session = await composio.experimental.toolRouter.createSession('user_123', {
3   toolkits: ['gmail', 'slack', 'github'],
4 });
5 
6 // Create session with auth configs
7 const session = await composio.experimental.toolRouter.createSession('user_456', {
8   toolkits: [
9     { toolkit: 'gmail', authConfigId: 'ac_gmail_work' },
10     { toolkit: 'slack', authConfigId: 'ac_slack_team' },
11     { toolkit: 'github', authConfigId: 'ac_github_personal' },
12   ],
13   manuallyManageConnections: true,
14 });
15 
16 console.log('Session ID:', session.sessionId);
17 console.log('MCP URL:', session.url);

Advanced Multi-Service Integration:

1 // Complex workflow session
2 const integrationSession = await composio.experimental.toolRouter.createSession('user_789', {
3   toolkits: [
4     { toolkit: 'gmail', authConfigId: 'ac_gmail_work' },
5     { toolkit: 'slack', authConfigId: 'ac_slack_team' },
6     { toolkit: 'github', authConfigId: 'ac_github_personal' },
7     { toolkit: 'notion', authConfigId: 'ac_notion_workspace' },
8     { toolkit: 'calendar', authConfigId: 'ac_gcal_primary' },
9   ],
10 });
11 
12 // Use with any MCP client
13 const mcpClient = new MCPClient(integrationSession.url);

Framework-Specific Examples:

1 // Mastra Integration
2 const mcpSession = await composio.experimental.toolRouter.createSession(userId, {
3   toolkits: ["gmail"],
4   manuallyManageConnections: true,
5 });
6 
7 const agent = new MastraAgent({
8   name: 'Gmail Assistant',
9   model: openai('gpt-4o-mini'),
10   tools: await mcpClient.getTools(),
11 });
12 
13 // OpenAI Agents Integration
14 const tools = [
15   hostedMcpTool({
16     serverLabel: 'composio tool router',
17     serverUrl: mcpSession.url,
18     requireApproval: {
19       never: { toolNames: ['GMAIL_FETCH_EMAILS'] },
20     },
21   }),
22 ];

Python SDK (v0.8.17)

Added: MCP Support

Core MCP Features:

Server Configuration: Create and manage MCP server configurations
Toolkit Management: Support for both simple toolkit names and detailed configurations
Authentication Control: Per-toolkit auth config specification
Tool Filtering: Specify allowed tools across all toolkits
User Instance Generation: Generate user-specific MCP server instances

Basic Usage:

1 from composio import Composio
2 
3 composio = Composio()
4 
5 # Create MCP server with toolkit configurations
6 server = composio.mcp.create(
7     'personal-mcp-server',
8     toolkits=[
9         {
10             'toolkit': 'github',
11             'auth_config_id': 'ac_xyz',
12         },
13         {
14             'toolkit': 'slack', 
15             'auth_config_id': 'ac_abc',
16         },
17     ],
18     allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
19     manually_manage_connections=False
20 )
21 
22 # Generate server instance for a user
23 mcp_instance = server.generate('user_12345')
24 print(f"MCP URL: {mcp_instance['url']}")

Simple Toolkit Usage:

1 # Using simple toolkit names
2 server = composio.mcp.create(
3     'simple-mcp-server',
4     toolkits=['composio_search', 'text_to_pdf'],
5     allowed_tools=['COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH', 'TEXT_TO_PDF_CONVERT_TEXT_TO_PDF']
6 )
7 
8 # All tools from toolkits (default behavior)
9 server = composio.mcp.create(
10     'all-tools-server',
11     toolkits=['composio_search', 'text_to_pdf']
12     # allowed_tools=None means all tools from these toolkits
13 )

LangChain Integration:

1 import asyncio
2 from composio import Composio
3 from langchain_mcp_adapters.client import MultiServerMCPClient
4 from langgraph.prebuilt import create_react_agent
5 
6 composio = Composio()
7 
8 mcp_config = composio.mcp.create(
9     name="langchain-slack-mcp",
10     toolkits=[{"toolkit": "slack", "auth_config_id": "<auth-config-id>"}],
11 )
12 
13 mcp_server = mcp_config.generate(user_id='<user-id>')
14 
15 client = MultiServerMCPClient({
16     "composio": {
17         "url": mcp_server["url"],
18         "transport": "streamable_http",
19     }
20 })
21 
22 async def langchain_mcp(message: str):
23     tools = await client.get_tools()
24     agent = create_react_agent("openai:gpt-4.1", tools)
25     response = await agent.ainvoke({"messages": message})
26     return response
27 
28 response = asyncio.run(langchain_mcp("Show me 20 most used slack channels"))

Added: Experimental ToolRouter

Core ToolRouter Features:

Session Management: Create isolated tool routing sessions for users
Toolkit Configuration: Support for both simple toolkit names and detailed configurations
Session Isolation: Each session gets its own MCP URL and session ID
Flexible Authentication: Per-session auth config management
Scoped Tool Access: Control which tools are available within each session

Basic Usage:

1 from composio import Composio
2 
3 composio = Composio()
4 
5 # Create a tool router session
6 session = composio.experimental.tool_router.create_session(
7     user_id='user_123',
8     toolkits=['github', 'slack'],
9     manually_manage_connections=False
10 )
11 
12 print(f"Session ID: {session['session_id']}")
13 print(f"MCP URL: {session['url']}")

Advanced Configuration:

1 # Create session with detailed toolkit configurations
2 session = composio.experimental.tool_router.create_session(
3     user_id='user_456',
4     toolkits=[
5         {
6             'toolkit': 'github',
7             'auth_config_id': 'ac_github_123'
8         },
9         {
10             'toolkit': 'slack', 
11             'auth_config_id': 'ac_slack_456'
12         }
13     ],
14     manually_manage_connections=True
15 )
16 
17 # Minimal session (no specific toolkits)
18 session = composio.experimental.tool_router.create_session(
19     user_id='user_789'
20 )

Integration with AI Frameworks:

1 import asyncio
2 from composio import Composio
3 from langchain_mcp_adapters.client import MultiServerMCPClient
4 
5 composio = Composio()
6 
7 # Create tool router session
8 session = composio.experimental.tool_router.create_session(
9     user_id='ai_user',
10     toolkits=['composio_search', 'text_to_pdf']
11 )
12 
13 # Use with LangChain MCP client
14 client = MultiServerMCPClient({
15     "composio": {
16         "url": session["url"],
17         "transport": "streamable_http",
18     }
19 })
20 
21 async def use_tool_router():
22     tools = await client.get_tools()
23     # Use tools in your AI workflow
24     return tools
25 
26 tools = asyncio.run(use_tool_router())

Migration Guide

TypeScript SDK: Migrating to New MCP API

The new MCP API provides enhanced functionality and better integration patterns. Here’s how to migrate from the previous MCP implementation:

Before (Legacy MCP)

1 // Legacy MCP approach (still accessible via deprecated.mcp)
2 import { Composio } from '@composio/core';
3 
4 const composio = new Composio();
5 
6 // Old MCP server creation
7 const legacyMCP = await composio.deprecated.mcp.createServer({
8   name: 'my-server',
9   toolkits: ['github', 'gmail'],
10 });
11 
12 // Direct URL usage
13 const mcpUrl = legacyMCP.url;

After (New MCP API)

1 // New MCP API approach
2 import { Composio } from '@composio/core';
3 
4 const composio = new Composio({
5   apiKey: process.env.COMPOSIO_API_KEY,
6 });
7 
8 // Step 1: Create MCP configuration
9 const mcpConfig = await composio.mcp.create('my-server', {
10   toolkits: [
11     { toolkit: 'github', authConfigId: 'ac_github_123' },
12     { toolkit: 'gmail', authConfigId: 'ac_gmail_456' }
13   ],
14   allowedTools: ['GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL'],
15   manuallyManageConnections: false,
16 });
17 
18 // Step 2: Generate user-specific server instance
19 const serverInstance = await composio.mcp.generate('user_123', mcpConfig.id);
20 const mcpUrl = serverInstance.url;

Key Migration Changes

Two-Step Process:
- Before: Single step server creation
- After: Create configuration, then generate user instances
Enhanced Configuration:
- Before: Simple toolkit names only
- After: Detailed toolkit configs with auth, tool filtering, connection management
User-Specific URLs:
- Before: Single server URL for all users
- After: Unique URLs per user for better isolation
Backward Compatibility:
- Legacy Access: Old MCP functionality remains available via composio.deprecated.mcp
- Gradual Migration: Migrate at your own pace without breaking existing implementations

Migration Benefits

Better Security: User-specific sessions with isolated access
Enhanced Control: Fine-grained toolkit and tool management
Framework Integration: Native support for modern AI frameworks
Scalability: Better resource management and user isolation

Migration Timeline

Phase 1: New MCP API available alongside legacy implementation
Phase 2: Legacy MCP accessible via deprecated.mcp namespace
Phase 3: Full deprecation (timeline to be announced)

Recommendation: Start new projects with the new MCP API and gradually migrate existing implementations to benefit from enhanced features and better framework integration.

Key Benefits & Use Cases

Development & Testing

Isolated Environments: Test different toolkit combinations without affecting production
Scoped Access: Limit tool access for security and testing purposes
Framework Flexibility: Works with any MCP-compatible client or framework

Production Workflows

Multi-Service Integration: Seamlessly combine tools from different services
User-Specific Sessions: Each user gets their own isolated session with appropriate permissions
Authentication Management: Fine-grained control over authentication per toolkit

Framework Compatibility

Vercel AI: Native integration with Vercel AI SDK
Mastra: Full support for Mastra agents and workflows
OpenAI Agents: Direct integration with OpenAI’s agent framework
LangChain: Complete LangGraph and LangChain compatibility
Custom Clients: Works with any MCP-compatible client

Enterprise Features

Session Management: Track and manage multiple user sessions
Resource Control: Limit concurrent sessions and resource usage
Audit Trail: Full logging and monitoring of tool usage
Security: Isolated sessions prevent cross-user data access

Migration & Compatibility

Both MCP and ToolRouter features are designed to complement existing Composio functionality:

1 // Can be used alongside regular tool management
2 const regularTools = await composio.tools.get({ toolkits: ['github'] });
3 const mcpSession = await composio.experimental.toolRouter.createSession(userId, {
4   toolkits: ['gmail', 'slack']
5 });
6 
7 // Both approaches can coexist and serve different purposes

The experimental ToolRouter API provides a preview of advanced session management capabilities, while the MCP API offers production-ready Model Control Protocol support for modern AI frameworks.

Bug Fixes

Fixed: ToolRouter Dependency Issue

Python SDK (v0.8.19)

Issue Fixed:

ToolRouter Functionality: Fixed ToolRouter tests that were failing due to missing tool_router attribute in HttpClient
Dependency Update: Updated composio-client dependency from version 1.9.1 to 1.10.0+ to include ToolRouter functionality
Version Compatibility: Resolved compatibility issues between ToolRouter implementation and client library

Details: ToolRouter functionality was briefly broken in versions 0.8.15 to 0.8.18 due to a dependency version mismatch. The composio-client library version 1.9.1 did not include the tool_router attribute, causing all ToolRouter integration tests to fail with AttributeError: 'HttpClient' object has no attribute 'tool_router'.

This has been fixed in version 0.8.19 by:

Updating the composio-client dependency to version 1.10.0+
Ensuring all ToolRouter functionality is now available
All ToolRouter integration tests now pass successfully

Previous Issue:

1 # This would fail in versions 0.8.15-0.8.18
2 session = composio.experimental.tool_router.create_session(user_id='test')
3 # AttributeError: 'HttpClient' object has no attribute 'tool_router'

Fixed in 0.8.19:

1 # This now works correctly
2 session = composio.experimental.tool_router.create_session(user_id='test')
3 # Returns: {'session_id': '...', 'url': '...'}

Fixed: Missing Descriptions in Auth Config Fields

Python SDK (v0.8.17) & TypeScript SDK (v0.1.53)

Issue Fixed:

Auth Config Connection Fields: Added missing descriptions to toolkit auth configuration connection fields
Auth Config Creation Fields: Added missing descriptions to toolkit auth configuration creation fields
Field Documentation: Improved field documentation and help text for better developer experience

Details: Previously, when developers were setting up auth configurations for toolkits, many fields lacked proper descriptions, making it difficult to understand what information was required. This fix ensures all auth config fields now include:

Clear, descriptive field labels
Helpful placeholder text where appropriate
Detailed explanations of field requirements

This improvement affects all toolkits and makes the authentication setup process more intuitive and error-free.

September 16, 2025

Toolkit Versioning in SDKs

Composio Toolkit Versioning provides granular control over tool versions across all your integrations. Instead of always using the latest version of tools, developers can now specify exact toolkit versions, ensuring consistent behavior and controlled updates in production environments.

Why Use Toolkit Versioning?

Version Stability: Pin specific toolkit versions to avoid unexpected changes in production
Controlled Updates: Test new toolkit versions before deploying to production
Environment Consistency: Ensure the same toolkit versions across development, staging, and production
Rollback Capability: Easily revert to previous toolkit versions if issues arise
Fine-grained Control: Set different versions for different toolkits based on your needs

Python SDK (v0.8.11)

Added

Toolkit Versioning Support: New toolkit_versions parameter for controlling tool versions
- Added toolkit_versions parameter to Composio class initialization
- Support for global version setting (e.g., 'latest')
- Support for per-toolkit version mapping (e.g., {'github': '20250902_00', 'slack': '20250902_00'})
- Environment variable support with COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME> pattern
- New toolkit_version.py utility module for version resolution logic

Examples:

1 # Global version for all toolkits, only `latest` is supported
2 composio = Composio(toolkit_versions='latest')
3 
4 # Per-toolkit version mapping
5 composio = Composio(toolkit_versions={
6     'github': '20250902_00',
7     'slack': '20250902_00',
8     'gmail': '20250901_01'
9 })
10 
11 # Using environment variables
12 # Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
13 composio = Composio()  # Automatically picks up env vars
14 
15 # Get tools with specific versions
16 tools = composio.tools.get('default', {'toolkits': ['github']})

TypeScript SDK (v0.1.52)

Added

Toolkit Versioning Support: Added toolkitVersions configuration option
- New toolkitVersions parameter in Composio class constructor
- Support for global version string or per-toolkit version mapping
- Environment variable parsing with getToolkitVersionsFromEnv() utility
- Enhanced getRawComposioToolBySlug() method for version-specific tool retrieval
- Version-aware tool filtering and search capabilities

Examples:

1 // Global version for all toolkits
2 const composio = new Composio({
3   toolkitVersions: '20250902_00'
4 });
5 
6 // Per-toolkit version mapping
7 const composio = new Composio({
8   toolkitVersions: {
9     'github': '20250902_00',
10     'slack': '20250902_00',
11     'gmail': '20250901_01'
12   }
13 });
14 
15 // Using environment variables
16 // Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
17 const composio = new Composio(); // Automatically picks up env vars
18 
19 // Get specific tool version
20 const tool = await composio.tools.getRawComposioToolBySlug(
21   'GITHUB_GET_REPO', 
22 );
23 
24 // Get tools with version-aware filtering
25 const tools = await composio.tools.get('default', {
26   toolkits: ['github'],
27   limit: 10
28 });

Key Benefits

Environment Variables: Set COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_NAME>=<VERSION> for automatic version resolution
Flexible Configuration: Choose between global versions or per-toolkit version mapping
Backward Compatibility: Existing code works unchanged - versioning is opt-in
Version Fallback: Automatically falls back to ‘latest’ when no version is specified
Cross-Platform Consistency: Identical developer experience across Python and TypeScript

Version Format

Toolkit versions follow the format: YYYYMMDD_NN (e.g., 20250902_00) or use 'latest' for the most recent version only supported at global scope and not individual toolkit level.

Environment Variables

$ # Set specific versions for different toolkits
> export COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
> export COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00
> export COMPOSIO_TOOLKIT_VERSION_GMAIL=20250901_01

Migration Note

This feature is fully backward compatible. Existing code will continue to work without changes, using the latest versions by default. To enable versioning, simply add the toolkit_versions parameter during SDK initialization.

Additional Updates

Package Updates: Bumped all Python provider packages to v0.8.10
Documentation: Enhanced API documentation with versioning examples
Testing: Added comprehensive test coverage (400+ new test cases) for versioning functionality
Examples: New versioning examples demonstrating practical usage patterns

September 15, 2025

Introducing Composio Auth Links

Composio Auth Links provide a hosted authentication solution that eliminates the need for developers to build custom authentication forms. Instead of manually rendering OAuth consent screens, API key input forms, or custom authentication fields, developers can simply redirect users to a Composio-hosted URL that handles the entire authentication process automatically.

Why Use Auth Links?

Zero UI Development: No need to build forms for OAuth, API keys, or custom fields like subdomains
Universal Authentication: Works seamlessly across all supported third-party services
Reduced Complexity: Replace complex OAuth flows with a simple redirect
Better UX: Professional, consistent authentication experience for end users
Faster Integration: Get authentication working in minutes, not hours

Python SDK (v0.8.11)

Added

Composio Connect Link Support: New link() method for creating external authentication links
- Added link() method to ConnectedAccounts class for generating user authentication links
- Support for callback URL redirection after authentication
- Enhanced user experience with external link-based authentication flow
- No manual form rendering required - Composio handles all authentication UI

Examples:

1 # Basic usage - create a connection request
2 connection_request = composio.connected_accounts.link('user_123', 'auth_config_123')
3 redirect_url = connection_request.redirect_url
4 print(f"Visit: {redirect_url} to authenticate your account")
5 
6 # Wait for the connection to be established
7 connected_account = connection_request.wait_for_connection()
8 
9 # With callback URL
10 connection_request = composio.connected_accounts.link(
11     'user_123',
12     'auth_config_123',
13     callback_url='<https://your-app.com/callback>'
14 )

TypeScript SDK (v0.1.51)

Added

Composio Connect Links: Added support for composio connect links
- New link() method in ConnectedAccounts class for generating authentication URLs
- Support for callback URL redirection with CreateConnectedAccountLinkOptions
- Comprehensive TypeScript types and validation for link creation options
- Eliminates need for custom authentication forms - just redirect users to the link

Examples:

1 // Basic usage - create a connection request
2 const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123');
3 const redirectUrl = connectionRequest.redirectUrl;
4 console.log(`Visit: ${redirectUrl} to authenticate your account`);
5 
6 // Wait for the connection to be established
7 const connectedAccount = await connectionRequest.waitForConnection();
8 
9 // With callback URL
10 const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123', {
11   callbackUrl: '<https://your-app.com/callback>'
12 });

Key Benefits

No Form Building: Composio handles OAuth consent, API key collection, and custom field inputs
Hosted Authentication Flow: Professional UI that works across all supported services
Callback URL Support: Control where users return after successful authentication
Connection Waiting: Built-in polling to detect when authentication completes
Cross-Platform Consistency: Identical developer experience across Python and TypeScript

Customisation

You can customise the app logo and name showed in the authentication page via the dashboard. Head over your project via platform.composio.dev and choose Settings → Auth Links to upload a new logo and change the name.

Migration Note

This feature replaces manual authentication form development with a simple redirect-based approach, significantly reducing integration time and complexity while providing a better user experience. Auth links are drop in replacement for composio.connectedAccounts.initate, you can safely swap this to composio.connectedAccounts.link

MCP (Model Control Protocol) & Experimental ToolRouter

Why Use MCP & ToolRouter?

TypeScript SDK (v0.1.53)

Added: MCP API

Added: Experimental ToolRouter

Python SDK (v0.8.17)

Added: MCP Support

Added: Experimental ToolRouter

Migration Guide

TypeScript SDK: Migrating to New MCP API

Before (Legacy MCP)

After (New MCP API)

Key Migration Changes

Migration Benefits

Migration Timeline

Key Benefits & Use Cases

Development & Testing

Production Workflows

Framework Compatibility

Enterprise Features

Migration & Compatibility

Bug Fixes

Fixed: ToolRouter Dependency Issue

Fixed: Missing Descriptions in Auth Config Fields

Toolkit Versioning in SDKs

Why Use Toolkit Versioning?

Python SDK (v0.8.11)

TypeScript SDK (v0.1.52)

Key Benefits

Version Format

Environment Variables

Migration Note

Additional Updates

Introducing Composio Auth Links

Why Use Auth Links?

Python SDK (v0.8.11)

TypeScript SDK (v0.1.51)

Key Benefits

Customisation

Migration Note