Changelog

Summary

This release includes significant authentication and configuration improvements across 16+ toolkits. The changes standardize Base URL handling, modernize authentication methods, and fix various endpoint configurations to improve reliability and flexibility.

Breaking Changes

We verified that active usage for these toolkits is practically zero before proceeding with these changes.

Make Toolkit

• Removed Region field in favor of explicit Base URL configuration
• Users must now provide the full Base URL instead of selecting a region
• This change provides more flexibility for custom deployments and regional endpoints

Bubble Toolkit

• Removed Subdomain field and restructured Base URL handling
• Users must now provide the complete Base URL instead of just the Subdomain
• This change standardizes URL configuration across all toolkits

Deprecated Features

HelloBar Toolkit

• Bearer authentication is now deprecated
• While still functional, users are encouraged to migrate to newer authentication methods
• Support for bearer tokens will be removed in a future release

FormSite Toolkit

• Bearer authentication deprecated in favor of API key authentication
• New integrations should use API key authentication for improved security
• Existing bearer token implementations will continue to work but should be migrated

Improvements & Fixes

Configuration Improvements

Linear Toolkit - Base URL is no longer a configurable field. The toolkit now uses a fixed endpoint, simplifying the authentication process.

Kibana Toolkit - Removed the default value for Base URL, allowing for more flexible deployment configurations. Users can now specify custom Kibana instances without overriding defaults.

Gong Toolkit - Added a sensible default value for Base URL to simplify initial setup. New users can connect without manually configuring the endpoint.

Insightly Toolkit - Added default value for the Pod field to streamline configuration. Reduces setup complexity for standard deployments.

ClickUp Toolkit - Fixed the Base URL field type for proper validation and handling. Ensures consistent URL formatting across all operations.

Dynamic Endpoint Updates

Brilliant Directories Toolkit - Implemented dynamic Base URL resolution for the Get Current User Endpoint. Automatically adapts to different deployment environments.

Braintree Toolkit - Updated configuration to use production defaults. Implemented dynamic endpoint resolution for better environment handling. Improved reliability for production deployments.

Auth0 Toolkit - Replaced hardcoded endpoints with dynamic tenant-based URL resolution. Supports multi-tenant deployments without manual configuration. Automatically constructs the correct endpoint based on the tenant configuration.

Endpoint Fixes

DataScope Toolkit - Fixed the Get Current User Endpoint to use the correct API path. Resolves authentication verification issues.

D2L Brightspace Toolkit - Updated the Get Current User Endpoint to match the latest API specifications. Ensures proper user identification and session validation.

Migration Guide

For toolkits with breaking changes, please update your configurations as follows:

1. Make: Replace Region with the full Base URL (e.g., https://us-east-1.make.com)
2. Bubble: Replace Subdomain with the full Base URL (e.g., https://myapp.bubbleapps.io)

For deprecated authentication methods:

• HelloBar & FormSite: Generate new API keys from your account settings and update your authentication configuration

We've updated authentication configurations for several toolkits to improve security, fix issues, and support additional deployment options.

Summary

Breaking Changes

These toolkits had incorrect or outdated authentication configurations that needed fixing. We verified that active usage for these toolkits is practically zero before proceeding with these changes.

Impact: Existing connections will stop working. You'll need to create new auth configs and ask affected users to reconnect.

Make

Replaced region-based configuration with full base URL input. Users now provide the complete Make instance URL (e.g., https://us2.make.com or https://us1.make.celonis.com) instead of just a region code.

Recall AI

Updated from region-based to full base URL configuration. Fixed field descriptions and metadata. Updated categories to AI/Productivity/Communication and added proper documentation links.

Relevance AI

Simplified authentication by removing deprecated Project ID field. Added conditional mapping for region codes to API subdomains (AU→f1db6c, EU→d7b62b, US→bcbe5a). Region field now defaults to US.

SmartRecruiters

Fixed OAuth configuration with correct SmartRecruiters endpoints. Added proper default scopes for candidates, jobs, and users. Enabled PKCE and added refresh token support.

Deprecated (Still Working)

These changes introduce new auth methods while keeping old ones functional:

Ashby

Added new API Key authentication scheme with automatic base64 encoding and proper authorization headers.

No Action Required: Old Basic Auth method is deprecated but continues to work. Existing connections are unaffected.

Freshdesk

Added new API Key authentication scheme requiring subdomain and API key with automatic base64 encoding.

No Action Required: Old Basic Auth method is deprecated but continues to work. Existing connections are unaffected.

Freshservice

Added new API Key authentication scheme requiring subdomain and API key with automatic base64 encoding.

No Action Required: Old Basic Auth method is deprecated but continues to work. Existing connections are unaffected.

Trello

Marked Bearer Token authentication as deprecated in favor of OAuth authentication.

No Action Required: Old Bearer auth continues to function. OAuth is recommended for new connections.

ZoomInfo

Added new OAuth2 authentication scheme with comprehensive scopes for contacts, companies, audiences, scoops, news, and intent data. Deprecated the old JWT-based Basic authentication. Password field now properly marked as secret.

No Action Required: Old JWT auth continues to function. New connections will use OAuth2.

Non-Breaking Improvements

Mixpanel

Fixed region mapping logic for data residency. Added proper conditional evaluation to map regions to correct API hosts (EU, India, or Standard). Region field is now optional and defaults to Standard server. Service account secret now properly marked as secret.

No Action Required: Existing connections continue to work without changes.

Supabase

Changed base_url field type from auth_config_field to connection_field for both OAuth and API Key schemes. Updated base action logic to respect user-provided base URLs, enabling support for self-hosted Supabase instances.

No Action Required: Existing connections continue to work. Self-hosted instances now supported.

What's Changed

We're deprecating 15 toolkits that currently have no supported actions. These toolkits will be reactivated once we add functional actions to them, ensuring you only see integrations that are ready to use.

Deprecated Toolkits

The following toolkits are now deprecated:

• BREATHEHR, DIXA, EGNYTE, EXPENSIFY, FREEAGENT
• GUSTO, NUTSHELL, OPENNUTRITION, OYSTERHR, RAKUTEN
• SALESFLARE, TEAMLEADER, WALGREENS, WHOOP, WIX

Impact on Your Integration

API Behavior Changes

List Toolkits Endpoint

The GET /toolkits endpoint will now exclude deprecated toolkits by default.

Need to see deprecated toolkits? Use the include_deprecated query parameter.

Backward Compatibility

Your existing integrations are safe. All other endpoints continue to work with deprecated toolkits:

• Retrieve the toolkit details
• Create auth configurations
• Manage connected accounts
• Configure MCP Servers

This ensures zero breaking changes to your current implementations.

Why This Matters

This change helps you:

• Focus on working integrations - No clutter from non-functional toolkits
• Avoid integration attempts with toolkits that have no actions
• Better developer experience with a cleaner, more actionable toolkit list

Questions?

If you have questions or need support with any deprecated toolkit, reach out to our team or check our documentation.

What's Changed

We're deprecating 60 toolkits that currently have no supported actions. These toolkits will be reactivated once we add functional actions to them, ensuring you only see integrations that are ready to use.

Deprecated Toolkits

The following toolkits are now deprecated:

• ACCELO, ADOBE, AERO_WORKFLOW, AMAZON, APEX27
• APPOINTO, APPSFLYER, ATLASSIAN, AUTH0, AXONAUT
• BATTLENET, BOLDSIGN, BRAINTREE, BREEZY_HR, BREX_STAGING
• BRIGHTPEARL, BROWSERHUB, CUSTOMER_IO, DEEL, DRIP_JOBS
• EPIC_GAMES, FACTORIAL, FITBIT, FRONT, GO_TO_WEBINAR
• GURU, HELCIM, HIGHLEVEL, ICIMS_TALENT_CLOUD, IDEA_SCALE
• KEAP, LASTPASS, LEVER_SANDBOX, LEXOFFICE, MANY_CHAT
• MBOUM, MICROSOFT_TENANT, MOXIE, ONCEHUB, POPTIN
• PRECORO, PRINTNODE, QUALAROO, RAVENSEOTOOLS, RING_CENTRAL
• RIPPLING, SAGE, SALESFORCE_MARKETING_CLOUD, SEISMIC, SMARTRECRUITERS
• TAPFORM, TERMINUS, TIMEKIT, TWITCH, VENLY
• VERO, VISME, WAVE_ACCOUNTING, WIZ, ZOHO_DESK

Impact on Your Integration

API Behavior Changes

List Toolkits Endpoint

The GET /toolkits endpoint will now exclude deprecated toolkits by default.

Need to see deprecated toolkits? Use the new include_deprecated query parameter.

Backward Compatibility

Your existing integrations are safe. All other endpoints continue to work with deprecated toolkits:

• Retrieve the toolkit details
• Create auth configurations
• Manage connected accounts
• Configure MCP Servers

This ensures zero breaking changes to your current implementations.

Why This Matters

This change helps you:

• Focus on working integrations - No clutter from non-functional toolkits
• Avoid integration attempts with toolkits that have no actions
• Better developer experience with a cleaner, more actionable toolkit list

Questions?

If you have questions or need support with any deprecated toolkit, reach out to our team or check our documentation.

We're cleaning up the Toolkits API by deprecating the is_local_toolkit response field and removing the is_local query parameter filter.

What's Changing?

Response Field: is_local_toolkit (Deprecated)

The is_local_toolkit field in toolkit API responses is now deprecated. This field was originally intended to indicate whether a toolkit was local to a specific project, but it is no longer meaningful as no toolkits use this classification.

Affected Endpoints:

• GET /api/v3/toolkits - List toolkits
• GET /api/v3/toolkits/{slug} - Get single toolkit
• GET /api/v3/toolkits/multi - Get multiple toolkits

The field will continue to be returned in API responses for backward compatibility, but it will always return false. It is marked as deprecated: true in the OpenAPI specification.

Query Parameter: is_local (Removed)

The is_local query parameter filter has been removed from the following endpoints:

• GET /api/v3/toolkits
• GET /api/v3/toolkits/multi

This parameter was used to filter toolkits by their local status, but since no toolkits are classified as local, it served no practical purpose.

Impact on Your Code

If You're Using the is_local Query Parameter

Before:

// This will no longer work
const toolkits = await fetch('/api/v3/toolkits?is_local=true');

After:

// Simply remove the is_local parameter
const toolkits = await fetch('/api/v3/toolkits');

If You're Reading the is_local_toolkit Response Field

The field will continue to be present in responses but will always return false. You can safely ignore this field or remove any logic that depends on it.

Before:

const toolkit = await composio.toolkits.get('github');
if (toolkit.is_local_toolkit) {
  // This condition will never be true
  handleLocalToolkit(toolkit);
}

After:

const toolkit = await composio.toolkits.get('github');
// Remove is_local_toolkit checks - they're no longer meaningful

The Composio SDKs achieved a significant milestone with Tool Router moving from experimental to stable production status in December 2025. The Tool Router is now a fully supported feature that enables creating isolated MCP sessions with scoped toolkit access across both Python 0.10.1 and TypeScript 0.3.0.

Major Achievements

Native Tool Execution: Both SDKs now support direct tool execution through Tool Router sessions. The TypeScript implementation emphasizes improved type safety and error handling, while Python developers benefit from better integration with provider-wrapped tools.

Webhook Security: A new verification method was introduced. The system now provides secure webhook endpoint validation and signature verification for incoming webhooks, enhancing protection for trigger-based workflows.

Framework Compatibility: The stable Tool Router integrates with multiple AI platforms including OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI, and Vercel AI SDK.

Technical Improvements

The TypeScript SDK resolved significant CommonJS compatibility issues by switching bundlers. This addresses a common developer pain point, particularly for Node.js projects not using ES modules.

The Python SDK extended LangChain provider support to version 1, while simultaneously fixing a critical KeyError occurring when SUPABASE_BETA_RUN_SQL_QUERY is used with Agents.

Migration Path

Users upgrading from experimental APIs should note the simplified approach—the Tool Router API now operates directly rather than through experimental namespaces, with comprehensive migration documentation provided.

The label query parameter has been removed from the GET /api/v3/connected_accounts endpoint.

What's changing?

The label query parameter is no longer supported when listing connected accounts. This parameter was previously accepted but had no functional behavior since label ingestion was removed in an earlier update.

Impact

None - This is a cleanup change. The label query parameter was not performing any filtering since the underlying label ingestion functionality was already removed. If your code was passing this parameter, it was being silently ignored.

Migration

No action required. If your code was passing the label query parameter, you can safely remove it from your API calls.

We've improved the security masking for REDACTED fields in the following APIs:

• Get Connected Account
• List Connected Accounts

What's Changed: Sensitive fields are now partially masked, revealing only the first 4 characters to help with debugging while maintaining security.

Example:

Before: REDACTED
After:  abcd...

Disabling Masking

If you need to disable masking for your use case, you have two options:

1. Via UI: Navigate to Project Settings → Configuration tab and update the masking settings
2. Via API: Use the Patch Project Config API

We've updated many toolkits so their outputs are now strongly typed objects instead of a generic response_data blob, meaning tools like Outlook, HubSpot, Notion, etc. now return well-shaped, documented fields you can rely on directly in your code and agents. These improvements apply to the latest toolkit versions—see our toolkit versioning docs for how versions are managed.

Why This Matters

• Better developer experience for direct execute: clear fields and types
• Improved agent performance: flatter output shapes with explicit fields reduce nesting and invalid params
• Clearer docs and type safety: richer metadata for IDEs and autocomplete

Before vs After

Previous (generic, version 20251202_00):

{
  "data": {
    "response_data": { "...": "..." }
  },
  "successful": true
}

Now (typed example – Outlook List Messages, version 20251209_00):

{
  "data": {
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('me')/messages",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=10",
    "value": [
      {
        "id": "abc123",
        "subject": "Hi there",
        "from": { "emailAddress": { "address": "a@b.com", "name": "Alice" } },
        "hasAttachments": true
      }
    ]
  },
  "successful": true
}

For the exact field mapping per toolkit, open platform.composio.dev → Toolkits → List Messages (or the relevant tool).

Migration Notes

• Breaking change for consumers on the latest version who post-process the old nested response_data shape: outputs are now flattened and explicitly typed.
• New and modified fields include richer descriptions and examples; some legacy placeholders were removed.
• Re-fetch schemas for your tool/version to see the typed definitions. Use the toolkit view in platform.composio.dev for authoritative field details.

What's Changing?

Starting today, the following applications will require your own developer credentials instead of Composio-managed credentials:

• Auth0
• Blackbaud
• BoldSign
• Deel
• Front
• GoToWebinar
• PagerDuty
• Pipedrive
• Shopify
• Strava
• SurveyMonkey
• Webex

What You Need to Do

To continue using these applications with Composio:

1. Create Developer Accounts: Register for developer accounts on the platforms you need
2. Generate API Credentials: Create OAuth apps following each platform's documentation
3. Configure in Composio: Add your credentials to Composio using custom auth configs
4. Test Your Integration: Test your integration with the new credentials

We're implementing automatic expiration for connected accounts that remain in incomplete states, helping maintain a cleaner and more efficient authentication system.

What's Changing?

Connected accounts in Initializing and Initiated states will now automatically expire after 10 minutes. This applies to connection attempts that were started but never completed.

Why This Matters

This change provides:

• Better Resource Management: Automatically cleans up incomplete connection attempts
• Improved System Hygiene: Prevents accumulation of stale, unused connection records
• Enhanced User Experience: Reduces clutter from abandoned authentication flows

Questions?

If you have any questions about this change, please reach out to our support team or check our Connected Accounts documentation.

We're strengthening the security of Model Context Protocol (MCP) URLs by making API key authentication mandatory for all requests.

What's Changing?

Starting December 15th, 2025, all new Composio projects must include the x-api-key header when making requests to MCP URLs. This header authenticates your application and ensures secure communication with the Composio platform.

Why This Matters

This change provides:

• Enhanced Authentication: Ensures only authorized applications can access MCP endpoints
• Industry Best Practices: Aligns with standard API security patterns

Impact on Existing Projects

For existing projects: We value backward compatibility and understand the need for a smooth transition. Your existing MCP URLs will continue to work without the x-api-key header until April 15th, 2026.

Important: After April 15th, 2026, all MCP URL requests without the x-api-key header will be rejected. Please ensure you update your applications before this date to avoid service disruption.

Note: If you're already passing the x-api-key header in your MCP requests, no action is required—you're all set!

Migration Guide

To adopt this security enhancement in your existing projects:

1. Locate Your API Key: Find your API key in the Composio dashboard under Project Settings
2. Update Your Code: Add the x-api-key header to all MCP URL requests
3. Test Thoroughly: Verify the updated requests work in your development environment
4. Deploy: Roll out the changes to your production environment

Questions?

If you have any questions about this security enhancement or need assistance with migration, please reach out to our support team or check our MCP documentation.

Summary

Added toolkit version support to trigger operations (create and getType) in both Python and TypeScript SDKs. This allows users to explicitly specify which toolkit version to use when creating trigger instances and retrieving trigger type information, ensuring consistent behavior across different toolkit versions.

Trigger operations now respect the global toolkitVersions configuration set during Composio initialization, providing better control over which trigger versions are used in your applications.

Key Changes

TypeScript SDK (ts/packages/core/)

• Added toolkit_versions parameter to triggers.create() method
  • Passes the global toolkit versions configuration when creating trigger instances
  • Defaults to 'latest' when no version is specified
• Modified triggers.getType() to respect global toolkit versions
  • Now accepts toolkit version configuration to fetch trigger types for specific versions
  • Improved error messages to include version-related fixes
• Updated trigger type documentation with comprehensive examples
• Added behavior documentation explaining version usage patterns

Python SDK (python/composio/core/models/)

• Added toolkit_versions parameter to triggers.create() method
  • Uses global toolkit version configuration when creating trigger instances
  • Converts None to omit for API compatibility
• Modified triggers.get_type() to respect toolkit versions
  • Implemented custom method replacing direct client binding
  • Passes toolkit version configuration to API calls
• Added comprehensive docstrings explaining version behavior

Behavior

Creating Triggers with Toolkit Versions:

// TypeScript - Configure versions at initialization
const composio = new Composio({
  apiKey: 'your-api-key',
  toolkitVersions: {
    gmail: '12082025_00',
    github: '10082025_01'
  }
});

// Create trigger - uses version '12082025_00' for Gmail
const trigger = await composio.triggers.create('user@example.com', 'GMAIL_NEW_MESSAGE', {
  connectedAccountId: 'ca_abc123',
  triggerConfig: {
    labelIds: 'INBOX',
    userId: 'me',
    interval: 60,
  },
});

# Python - Configure versions at initialization
composio = Composio(
    api_key="your-api-key",
    toolkit_versions={"gmail": "12082025_00", "github": "10082025_01"}
)

# Create trigger - uses version '12082025_00' for Gmail
trigger = composio.triggers.create(
    slug="GMAIL_NEW_MESSAGE",
    user_id="user@example.com",
    trigger_config={"labelIds": "INBOX", "userId": "me", "interval": 60}
)

Retrieving Trigger Types with Specific Versions:

// TypeScript
const composio = new Composio({
  apiKey: 'your-api-key',
  toolkitVersions: { github: '10082025_01' }
});

// Get trigger type for specific version
const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
// Returns trigger type for version '10082025_01'

# Python
composio = Composio(
    api_key="your-api-key",
    toolkit_versions={"github": "10082025_01"}
)

# Get trigger type for specific version
trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
# Returns trigger type for version '10082025_01'

Benefits

• Version Control: Explicitly specify which toolkit version to use for triggers
• Consistency: Ensure trigger behavior remains consistent across toolkit updates
• Testing: Test trigger integrations with specific versions before updating
• Debugging: Easier to debug issues by pinning to specific toolkit versions
• Production Safety: Avoid unexpected changes from automatic version updates

Migration Guide

This is a non-breaking change. Existing code will continue to work with default behavior:

Before (still works):

// Uses 'latest' version by default
const trigger = await composio.triggers.create('user', 'GITHUB_COMMIT_EVENT', {...});

After (recommended for production):

// Explicitly configure versions for better control
const composio = new Composio({
  apiKey: 'your-api-key',
  toolkitVersions: { github: '10082025_01' }
});

const trigger = await composio.triggers.create('user', 'GITHUB_COMMIT_EVENT', {...});

For more details on toolkit versioning, see the Toolkit Versioning documentation.

We're introducing improved security requirements for Model Context Protocol (MCP) URLs to ensure better isolation between user connections and prevent unauthorized access.

What's Changing?

Starting today, all new Composio projects must include at least one of the following parameters in their MCP URLs:

• user_id - Identifies the specific user
• connected_account_id - Identifies the specific connected account

Why This Matters

This change ensures that:

• User Isolation: Each user's connections remain completely separate from others
• Enhanced Security: Prevents potential cross-user data access scenarios
• Better Multi-Tenancy: Enables safer multi-tenant application architectures
• Explicit Access Control: Forces developers to explicitly specify which user or account context they're operating in

Impact on Existing Projects

For existing projects: We understand the importance of backward compatibility. While we've sent email notifications to project owners about upgrading their MCP URLs, your existing integrations will continue to work until January 15th, 2026.

Important: After January 15th, 2026, MCP URLs without user_id or connected_account_id query parameters will no longer be supported. Please ensure you update your MCP URLs before this date to avoid service disruption.

Note: If your MCP URLs already include either user_id or connected_account_id query parameters, no action is required—you can safely ignore this notice.

Implementation Example

Before:

https://platform.composio.dev/v3/mcp/{id}

After (with user_id):

https://platform.composio.dev/v3/mcp/{id}?user_id=user_123

After (with connected_account_id):

https://platform.composio.dev/v3/mcp/{id}?connected_account_id=ca_xyz

Migration Guide

If you're using an existing project and want to adopt this security enhancement:

1. Review your current MCP URL configuration
2. Add either user_id or connected_account_id parameter to your URLs
3. Update your application code to pass the appropriate identifier
4. Test the updated URLs in your development environment

For more details on choosing the right user identifiers for your application, see our User Management documentation.

Questions?

If you have any questions about this security enhancement or need assistance with migration, please reach out to our support team or check our MCP documentation.

Summary

Added version validation for manual tool execution to prevent unexpected behavior when using latest toolkit versions. This ensures users explicitly specify toolkit versions when executing tools manually, while allowing flexibility through a skip flag.

This release also eliminates a lot of redundant API calls made to check connected account during tool execution, effectively increasing the performance of tool execution.

Key Changes

Python SDK (python/)

• Added ToolVersionRequiredError exception with detailed error messages and fix suggestions
• Added dangerously_skip_version_check parameter to execute() method
• Modified _execute_tool() to validate version is not latest unless skip flag is set
• Automatically passes dangerously_skip_version_check=True for agentic provider flows
• Added comprehensive test coverage (19 test methods) in test_tool_execution.py

TypeScript SDK (ts/packages/core/)

• Added ComposioToolVersionRequiredError error class with possible fixes
• Added dangerouslySkipVersionCheck parameter to execute flow
• Modified tool execution to validate version before API calls
• Updated execution type definitions in tool.types.ts and modifiers.types.ts
• Updated test files with date-based version format (20251201_xx)
• Improved tool execution by eliminating redundant API calls

Behavior

Before: Tools could be executed with latest version, risking unexpected behavior on toolkit updates

After: Manual execution requires specific version or explicit skip flag:

# Raises ToolVersionRequiredError
tools.execute("GITHUB_CREATE_ISSUE", {...})

# Works - explicit version
tools.execute("GITHUB_CREATE_ISSUE", {...}, version="20251201_01")

# Works - configured toolkit versions
tools = Tools(client, provider, toolkit_versions={"github": "20251201_01"})

# Works - with skip flag (use cautiously)
tools.execute("GITHUB_CREATE_ISSUE", {...}, dangerously_skip_version_check=True)

Breaking Changes

Manual tool execution without version specification now throws an error. Users must either:

1. Pass explicit version parameter
2. Configure toolkit versions in SDK initialization
3. Set environment variable COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_SLUG>
4. Use dangerously_skip_version_check=True flag

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:

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

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

// Create MCP configuration
const mcpConfig = await composio.mcp.create('my-server-name', {
  toolkits: [
    { toolkit: 'github', authConfigId: 'ac_233434343' },
    { toolkit: 'gmail', authConfigId: 'ac_567890123' }
  ],
  allowedTools: ['GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL'],
  manuallyManageConnections: false,
});

// Generate server instance for a user
const serverInstance = await composio.mcp.generate('user123', mcpConfig.id);
console.log('MCP URL:', serverInstance.url);

Framework Integration Examples:

// Vercel AI Integration
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
import { experimental_createMCPClient as createMCPClient } from 'ai';

const mcpClient = await createMCPClient({
  name: 'composio-mcp-client',
  transport: new SSEClientTransport(new URL(serverInstance.url)),
});

// Mastra Integration
import { MCPClient as MastraMCPClient } from '@mastra/mcp';

const mcpClient = new MastraMCPClient({
  servers: {
    composio: { url: new URL(mcpSession.url) },
  },
});

// OpenAI Agents Integration
import { hostedMcpTool } from '@openai/agents';

const tools = [
  hostedMcpTool({
    serverLabel: 'composio',
    serverUrl: mcpSession.url,
  }),
];

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:

// Create session with simple toolkit names
const session = await composio.experimental.toolRouter.createSession('user_123', {
  toolkits: ['gmail', 'slack', 'github'],
});

// Create session with auth configs
const session = await composio.experimental.toolRouter.createSession('user_456', {
  toolkits: [
    { toolkit: 'gmail', authConfigId: 'ac_gmail_work' },
    { toolkit: 'slack', authConfigId: 'ac_slack_team' },
    { toolkit: 'github', authConfigId: 'ac_github_personal' },
  ],
  manuallyManageConnections: true,
});

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

Advanced Multi-Service Integration:

// Complex workflow session
const integrationSession = await composio.experimental.toolRouter.createSession('user_789', {
  toolkits: [
    { toolkit: 'gmail', authConfigId: 'ac_gmail_work' },
    { toolkit: 'slack', authConfigId: 'ac_slack_team' },
    { toolkit: 'github', authConfigId: 'ac_github_personal' },
    { toolkit: 'notion', authConfigId: 'ac_notion_workspace' },
    { toolkit: 'calendar', authConfigId: 'ac_gcal_primary' },
  ],
});

// Use with any MCP client
const mcpClient = new MCPClient(integrationSession.url);

Framework-Specific Examples:

// Mastra Integration
const mcpSession = await composio.experimental.toolRouter.createSession(userId, {
  toolkits: ["gmail"],
  manuallyManageConnections: true,
});

const agent = new MastraAgent({
  name: 'Gmail Assistant',
  model: openai('gpt-4o-mini'),
  tools: await mcpClient.getTools(),
});

// OpenAI Agents Integration
const tools = [
  hostedMcpTool({
    serverLabel: 'composio tool router',
    serverUrl: mcpSession.url,
    requireApproval: {
      never: { toolNames: ['GMAIL_FETCH_EMAILS'] },
    },
  }),
];

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:

from composio import Composio

composio = Composio()

# Create MCP server with toolkit configurations
server = composio.mcp.create(
    'personal-mcp-server',
    toolkits=[
        {
            'toolkit': 'github',
            'auth_config_id': 'ac_xyz',
        },
        {
            'toolkit': 'slack',
            'auth_config_id': 'ac_abc',
        },
    ],
    allowed_tools=['GITHUB_CREATE_ISSUE', 'SLACK_SEND_MESSAGE'],
    manually_manage_connections=False
)

# Generate server instance for a user
mcp_instance = server.generate('user_12345')
print(f"MCP URL: {mcp_instance['url']}")

Simple Toolkit Usage:

# Using simple toolkit names
server = composio.mcp.create(
    'simple-mcp-server',
    toolkits=['composio_search', 'text_to_pdf'],
    allowed_tools=['COMPOSIO_SEARCH_DUCK_DUCK_GO_SEARCH', 'TEXT_TO_PDF_CONVERT_TEXT_TO_PDF']
)

# All tools from toolkits (default behavior)
server = composio.mcp.create(
    'all-tools-server',
    toolkits=['composio_search', 'text_to_pdf']
    # allowed_tools=None means all tools from these toolkits
)

LangChain Integration:

import asyncio
from composio import Composio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent

composio = Composio()

mcp_config = composio.mcp.create(
    name="langchain-slack-mcp",
    toolkits=[{"toolkit": "slack", "auth_config_id": "<auth-config-id>"}],
)

mcp_server = mcp_config.generate(user_id='<user-id>')

client = MultiServerMCPClient({
    "composio": {
        "url": mcp_server["url"],
        "transport": "streamable_http",
    }
})

async def langchain_mcp(message: str):
    tools = await client.get_tools()
    agent = create_react_agent("openai:gpt-4.1", tools)
    response = await agent.ainvoke({"messages": message})
    return response

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:

from composio import Composio

composio = Composio()

# Create a tool router session
session = composio.experimental.tool_router.create_session(
    user_id='user_123',
    toolkits=['github', 'slack'],
    manually_manage_connections=False
)

print(f"Session ID: {session['session_id']}")
print(f"MCP URL: {session['url']}")

Advanced Configuration:

# Create session with detailed toolkit configurations
session = composio.experimental.tool_router.create_session(
    user_id='user_456',
    toolkits=[
        {
            'toolkit': 'github',
            'auth_config_id': 'ac_github_123'
        },
        {
            'toolkit': 'slack',
            'auth_config_id': 'ac_slack_456'
        }
    ],
    manually_manage_connections=True
)

# Minimal session (no specific toolkits)
session = composio.experimental.tool_router.create_session(
    user_id='user_789'
)

Integration with AI Frameworks:

import asyncio
from composio import Composio
from langchain_mcp_adapters.client import MultiServerMCPClient

composio = Composio()

# Create tool router session
session = composio.experimental.tool_router.create_session(
    user_id='ai_user',
    toolkits=['composio_search', 'text_to_pdf']
)

# Use with LangChain MCP client
client = MultiServerMCPClient({
    "composio": {
        "url": session["url"],
        "transport": "streamable_http",
    }
})

async def use_tool_router():
    tools = await client.get_tools()
    # Use tools in your AI workflow
    return tools

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)

// Legacy MCP approach (still accessible via deprecated.mcp)
import { Composio } from '@composio/core';

const composio = new Composio();

// Old MCP server creation
const legacyMCP = await composio.deprecated.mcp.createServer({
  name: 'my-server',
  toolkits: ['github', 'gmail'],
});

// Direct URL usage
const mcpUrl = legacyMCP.url;

After (New MCP API)

// New MCP API approach
import { Composio } from '@composio/core';

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

// Step 1: Create MCP configuration
const mcpConfig = await composio.mcp.create('my-server', {
  toolkits: [
    { toolkit: 'github', authConfigId: 'ac_github_123' },
    { toolkit: 'gmail', authConfigId: 'ac_gmail_456' }
  ],
  allowedTools: ['GITHUB_CREATE_ISSUE', 'GMAIL_SEND_EMAIL'],
  manuallyManageConnections: false,
});

// Step 2: Generate user-specific server instance
const serverInstance = await composio.mcp.generate('user_123', mcpConfig.id);
const mcpUrl = serverInstance.url;

Key Migration Changes

1. Two-Step Process:

   • Before: Single step server creation
   • After: Create configuration, then generate user instances

2. Enhanced Configuration:

   • Before: Simple toolkit names only
   • After: Detailed toolkit configs with auth, tool filtering, connection management

3. User-Specific URLs:

   • Before: Single server URL for all users
   • After: Unique URLs per user for better isolation

4. 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:

// Can be used alongside regular tool management
const regularTools = await composio.tools.get({ toolkits: ['github'] });
const mcpSession = await composio.experimental.toolRouter.createSession(userId, {
  toolkits: ['gmail', 'slack']
});

// 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:

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

Fixed in 0.8.19:

# This now works correctly
session = composio.experimental.tool_router.create_session(user_id='test')
# 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.

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:

# Global version for all toolkits, only `latest` is supported
composio = Composio(toolkit_versions='latest')

# Per-toolkit version mapping
composio = Composio(toolkit_versions={
    'github': '20250902_00',
    'slack': '20250902_00',
    'gmail': '20250901_01'
})

# Using environment variables
# Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
composio = Composio()  # Automatically picks up env vars

# Get tools with specific versions
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:

// Global version for all toolkits
const composio = new Composio({
  toolkitVersions: '20250902_00'
});

// Per-toolkit version mapping
const composio = new Composio({
  toolkitVersions: {
    'github': '20250902_00',
    'slack': '20250902_00',
    'gmail': '20250901_01'
  }
});

// Using environment variables
// Set COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00
const composio = new Composio(); // Automatically picks up env vars

// Get specific tool version
const tool = await composio.tools.getRawComposioToolBySlug(
  'GITHUB_GET_REPO',
);

// Get tools with version-aware filtering
const tools = await composio.tools.get('default', {
  toolkits: ['github'],
  limit: 10
});

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

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:

# Basic usage - create a connection request
connection_request = composio.connected_accounts.link('user_123', 'auth_config_123')
redirect_url = connection_request.redirect_url
print(f"Visit: {redirect_url} to authenticate your account")

# Wait for the connection to be established
connected_account = connection_request.wait_for_connection()

# With callback URL
connection_request = composio.connected_accounts.link(
    'user_123',
    'auth_config_123',
    callback_url='<https://your-app.com/callback>'
)

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:

// Basic usage - create a connection request
const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123');
const redirectUrl = connectionRequest.redirectUrl;
console.log(`Visit: ${redirectUrl} to authenticate your account`);

// Wait for the connection to be established
const connectedAccount = await connectionRequest.waitForConnection();

// With callback URL
const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123', {
  callbackUrl: '<https://your-app.com/callback>'
});

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