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);

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