Composio

• Tool Router - Create isolated, secure MCP sessions for AI agents with automatic authentication
• Direct Execution - Build traditional apps with manual tool execution and CRUD operations

Getting Started

📖 Prerequisites: Before using Composio, set up your API keys. See Setting Up API Keys for instructions on configuring Composio, OpenAI, and Anthropic API keys.

When to use

• Building chat-based or autonomous agents that need access to external tools (Gmail, Slack, GitHub, etc.)
• Creating multi-user applications with isolated tool access per session
• Implementing automatic authentication flows for external services
• Integrating with AI frameworks (Vercel AI SDK, LangChain, OpenAI Agents, Claude)
• Using MCP (Model Context Protocol) for dynamic tool discovery
• Building event-driven agents with triggers

• Creating CRUD applications that execute tools directly
• Building automation workflows without agent frameworks
• Managing connected accounts and authentication configurations
• Creating custom tools with specific authentication requirements
• Implementing multi-tenant applications with session isolation
• Building tools with pre/post-execution hooks and modifiers

1. Building Agents

• 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
• Real-time event handling with triggers

1.1 Session Management & Configuration

• 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

1.2 Authentication Flows

• Auto Authentication in Chat - Enable in-chat authentication flows
• Manual Authorization - Use session.authorize() for explicit flows
• Connection Management - Configure manageConnections, waitForConnections, and custom callback URLs

1.3 Toolkit Querying & UI Building

• Building Chat UIs - Build chat applications with toolkit selection, connection management, and session handling
• Query Toolkit States - Use session.toolkits() to check connections, filter toolkits, and build connection UIs

1.4 Event-Driven Agents (Triggers)

• 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

2. Building Apps with Composio Tools

• Direct tool execution with manual control
• CRUD operations on connected accounts, auth configs, and toolkits
• Custom tool creation with authentication
• Session isolation for multi-tenant apps
• Pre/post-execution hooks and modifiers
• Event-driven workflows with triggers

2.1 Core Operations

• Fetching Tools - Get tools with filters and search
• Direct Tool Execution - Execute tools manually with parameters
• Tool Version Management - Version pinning strategies for stability

2.2 Resource Management (CRUD Patterns)

• Connected Accounts CRUD - Create, read, update, delete connected accounts
• Auth Config Management - Manage authentication configurations
• Toolkit Management - Query toolkits, categories, and auth requirements

2.3 Extensibility & Customization

• Creating Custom Tools - Build standalone and toolkit-based tools
• Tool Modifiers - Schema modification and execution hooks

2.4 Event-Driven Applications

• 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 webhooks
• Managing Triggers - Enable, disable, update, and list triggers

2.5 User Context & Multi-Tenancy

• User ID Patterns - User vs organization IDs, shared vs isolated connections

Quick Start Examples

Building an Agent with Tool Router

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

const composio = new Composio();

// Create a session with Gmail tools
const session = await composio.create('user_123', {
  toolkits: ['gmail'],
  manageConnections: true
});

// Use MCP URL with any AI framework
console.log('MCP URL:', session.mcp.url);

Building an App with Direct Execution

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

const composio = new Composio({
  apiKey: 'your-api-key',
  toolkitVersions: { github: '12082025_00' }
});

// Fetch tools
const tools = await composio.tools.get('user_123', {
  toolkits: ['github']
});

// Execute a tool
const result = await composio.tools.execute('GITHUB_GET_REPO', {
  userId: 'user_123',
  arguments: { owner: 'composio', repo: 'sdk' },
});

console.log(result.data);

References

• Tool Router Docs
• MCP Protocol
• Framework Integration Examples

• Tools API
• Connected Accounts API
• Auth Configs API
• Toolkits API
• Custom Tools Guide
• Modifiers
• Core Concepts

• Triggers API
• Webhook Verification