Composio Tool Router
Comprehensive guide to building AI agents with Composio Tool Router - create isolated, secure tool sessions for your users with seamless authentication and toolkit management.
When to use
Use this skill when:
Building AI agents that need access to external tools (Gmail, Slack, GitHub, etc.) Creating multi-user applications with isolated tool access Implementing authentication flows for external services Managing toolkit connections and permissions Integrating with AI frameworks (Vercel AI SDK, LangChain, OpenAI Agents, Claude) Using MCP (Model Context Protocol) for tool discovery Building UI for connection management Core Concepts
Tool Router creates isolated MCP sessions for users with scoped access to toolkits and tools. It handles:
Session-based isolation per user Dynamic toolkit and tool configuration Automatic authentication management MCP-compatible server URLs for any AI framework Connection state querying for UI building Rules 1. Building Agents with Tool Router
Essential patterns for creating agent sessions and configuring tools:
User ID Best Practices - Choose user IDs for security and isolation Creating Basic Sessions - Initialize Tool Router sessions Session Lifecycle Best Practices - When to create new sessions vs reuse Session Configuration - Configure toolkits, tools, and filters Using Native Tools - Prefer native tools for performance and control Framework Integration - Connect with Vercel AI, LangChain, OpenAI Agents 2. Authenticating Users
Authentication patterns for seamless user experiences:
Auto Authentication in Chat - Enable in-chat authentication flows Manual Authorization - Use session.authorize() for explicit flows Connection Management - Configure manageConnections options Wait for Connections - Block until authentication completes Custom Callback URLs - Handle OAuth redirects 3. Fetching Toolkits and Connection Status
Build connection UIs and check toolkit states:
Query Toolkit States - Use session.toolkits() to check connections Build Connection UI - Display connection status and auth buttons Filter Toolkits - Query specific toolkits Pagination - Handle large toolkit lists Connection Details - Access auth configs and account info Advanced (Coming Soon) Session modifiers and middleware Custom tool configuration Workbench integration Experimental features Quick Start import { Composio } from '@composio/core';
// Create a session with Gmail tools const composio = new Composio(); const session = await composio.create('user_123', { toolkits: ['gmail'], manageConnections: true });
// Use with any MCP-compatible framework console.log('MCP URL:', session.mcp.url);
- Advanced Features (Triggers & Events)
Real-time event handling and webhook integration patterns:
Creating Triggers - Set up trigger instances for real-time events Subscribing to Events - Listen to trigger events in real-time Webhook Verification - Verify and process incoming webhook payloads Managing Triggers - Enable, disable, update, and list triggers References Tool Router Docs Triggers API Webhook Verification MCP Protocol TypeScript Examples