@devries-cameron20 / composio-1 / commits / 503bae8b1
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Add Tool Router documentation and restructure docs layout

- Rename welcome.mdx to index.mdx for cleaner /docs URL - Add complete Tool Router documentation section: - Quickstart guide with MCP and native tool integrations - Core concepts: users/sessions, authentication, tools/toolkits - Guides: in-chat auth, manual auth, multi-account, white-labeling - MCP client integration guide - Migration guide from beta to stable - Fix navigation active state for Tool Router tab - Update redirects for new URL structure

Sushmithamallesh committed Dec 30, 2025 at 18:31 UTC 503bae8b1173c9d14402ef2294c390bd6e1b40b4
18 files changed +2576 -6
fumadocs/content/docs/index.mdx renamed
fumadocs/content/docs/meta.json
+1 -1
@@ -1,7 +1,7 @@
1 {
2 "pages": [
3 "---Get Started---",
4 - "welcome",
4 + "index",
5 "quickstart",
6 "capabilities",
7 "---Tools and Triggers---",
fumadocs/content/tool-router/authentication.mdx new
+70
@@ -0,0 +1,70 @@
1 +---
2 +title: Authentication
3 +description: Understand how Tool Router handles user authentication to toolkits
4 +---
5 +
6 +Tool Router handles authentication through [Connect Links](/docs/authenticating-tools#hosted-authentication-connect-link), hosted pages where users complete OAuth or enter credentials.
7 +
8 +## In-chat authentication
9 +
10 +By default, when a tool requires authentication, the agent prompts the user with a Connect Link. The user authenticates and confirms in chat. The agent handles OAuth flows, token refresh, and credential management automatically.
11 +
12 +Here's what this looks like in a conversation:
13 +
14 +```
15 +You: Star the composio repo on GitHub
16 +
17 +Agent: I need you to connect your GitHub account first.
18 + Please click here to authorize: https://connect.composio.dev/link/ln_abc123
19 +
20 +You: Done
21 +
22 +Agent: Done! I've starred ComposioHQ/composio.
23 +```
24 +
25 +This flow works well for chat applications where users interact directly with the agent. See [Using in-chat authentication](/tool-router/using-in-chat-authentication).
26 +
27 +## Manual authentication
28 +
29 +For apps that manage auth outside of chat, use `session.authorize()` to generate Connect Links programmatically:
30 +
31 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
32 +<Tab value="Python">
33 +```python
34 +connection_request = session.authorize("github")
35 +print(connection_request.redirect_url)
36 +# https://connect.composio.dev/link/ln_abc123
37 +```
38 +</Tab>
39 +<Tab value="TypeScript">
40 +```typescript
41 +const connectionRequest = await session.authorize("github");
42 +console.log(connectionRequest.redirectUrl);
43 +// https://connect.composio.dev/link/ln_abc123
44 +```
45 +</Tab>
46 +</Tabs>
47 +
48 +Use this when you want users to connect accounts during onboarding, or when building a custom connections page. See [Manually authenticating users](/tool-router/manually-authenticating-users) for a detailed guide.
49 +
50 +## How Tool Router manages auth configs
51 +
52 +When executing a tool, Tool Router needs an auth config to find or create a connected account. It handles this automatically:
53 +
54 +1. Uses your `authConfigs` override if provided
55 +2. Otherwise, reuses an auth config it previously created for this toolkit
56 +3. If none exists, creates one using Composio managed auth
57 +
58 +You don't need to create auth configs manually for most toolkits.
59 +
60 +## Supported auth methods
61 +
62 +Tool Router supports **Composio managed OAuth** (GitHub, Gmail, Slack, and most toolkits) and **API key auth** (users enter their own keys via Connect Link).
63 +
64 +<Callout type="info">
65 +Toolkits without Composio managed auth require a custom auth config. See [Using custom auth configs](/tool-router/using-custom-auth-configs).
66 +</Callout>
67 +
68 +## White-labeling
69 +
70 +Show your own branding on OAuth consent screens by creating your own OAuth app. See [White-labeling authentication](/tool-router/white-labeling-authentication).
fumadocs/content/tool-router/managing-multiple-accounts.mdx new
+133
@@ -0,0 +1,133 @@
1 +---
2 +title: Managing multiple accounts
3 +description: Handle users with multiple accounts for the same toolkit
4 +---
5 +
6 +Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail accounts). This is useful when users need to manage different email accounts, GitHub organizations, or separate work and personal contexts. This guide explains how to connect, select, and manage multiple accounts.
7 +
8 +## Default account behavior
9 +
10 +When multiple accounts are connected for the same toolkit:
11 +- Each session can only use **one account per toolkit** at a time
12 +- Tool Router uses the **most recently connected account** by default
13 +- You can override this by explicitly selecting an account
14 +- Each account maintains its own authentication and permissions
15 +
16 +## Connecting multiple accounts
17 +
18 +Call `session.authorize()` multiple times for the same toolkit. Each authorization creates a separate connected account with its own ID. The most recently connected account becomes the active one for that session. New sessions will also use the most recent account unless you [explicitly select a different one](#selecting-a-specific-account-for-a-session).
19 +
20 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
21 +<Tab value="Python">
22 +```python
23 +session = composio.create(user_id="user_123")
24 +
25 +# Connect first account (work)
26 +work_auth = session.authorize("gmail")
27 +print(f"Connect work Gmail: {work_auth.redirect_url}")
28 +work_connection = work_auth.wait_for_connection()
29 +print(f"Work account connected: {work_connection.id}")
30 +
31 +# Connect second account (personal)
32 +personal_auth = session.authorize("gmail")
33 +print(f"Connect personal Gmail: {personal_auth.redirect_url}")
34 +personal_connection = personal_auth.wait_for_connection()
35 +print(f"Personal account connected: {personal_connection.id}")
36 +```
37 +</Tab>
38 +<Tab value="TypeScript">
39 +```typescript
40 +const session = await composio.create("user_123");
41 +
42 +// Connect first account (work)
43 +const workAuth = await session.authorize("gmail");
44 +console.log(`Connect work Gmail: ${workAuth.redirectUrl}`);
45 +const workConnection = await workAuth.waitForConnection();
46 +console.log(`Work account connected: ${workConnection.id}`);
47 +
48 +// Connect second account (personal)
49 +const personalAuth = await session.authorize("gmail");
50 +console.log(`Connect personal Gmail: ${personalAuth.redirectUrl}`);
51 +const personalConnection = await personalAuth.waitForConnection();
52 +console.log(`Personal account connected: ${personalConnection.id}`);
53 +```
54 +</Tab>
55 +</Tabs>
56 +
57 +<Callout type="info">
58 +Store the account IDs returned after connection to explicitly select accounts later.
59 +</Callout>
60 +
61 +## Selecting a specific account for a session
62 +
63 +Each Tool Router session can only use one account per toolkit at a time. To use a specific account in a session, pass it in the session config:
64 +
65 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
66 +<Tab value="Python">
67 +```python
68 +# This session will use a specific Gmail account
69 +session = composio.create(
70 + user_id="user_123",
71 + connected_accounts={
72 + "gmail": "ca_specific_account_id", # Connected account ID
73 + },
74 +)
75 +
76 +# To switch accounts, create a new session with a different account ID
77 +session2 = composio.create(
78 + user_id="user_123",
79 + connected_accounts={
80 + "gmail": "ca_different_account_id", # Different account
81 + },
82 +)
83 +```
84 +</Tab>
85 +<Tab value="TypeScript">
86 +```typescript
87 +// This session will use a specific Gmail account
88 +const session = await composio.create("user_123", {
89 + connectedAccounts: {
90 + gmail: "ca_specific_account_id", // Connected account ID
91 + },
92 +});
93 +
94 +// To switch accounts, create a new session with a different account ID
95 +const session2 = await composio.create("user_123", {
96 + connectedAccounts: {
97 + gmail: "ca_different_account_id", // Different account
98 + },
99 +});
100 +```
101 +</Tab>
102 +</Tabs>
103 +
104 +## Listing all user accounts
105 +
106 +To list all accounts a user has connected (not just the active one), see [List accounts](/docs/connected-accounts#list-accounts).
107 +
108 +## Viewing session's active account
109 +
110 +Use `session.toolkits()` to see which account is currently active in the session:
111 +
112 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
113 +<Tab value="Python">
114 +```python
115 +toolkits = session.toolkits()
116 +
117 +for toolkit in toolkits.items:
118 + if toolkit.connection.connected_account:
119 + print(f"{toolkit.name}: {toolkit.connection.connected_account.id}")
120 +```
121 +</Tab>
122 +<Tab value="TypeScript">
123 +```typescript
124 +const toolkits = await session.toolkits();
125 +
126 +for (const toolkit of toolkits.items) {
127 + if (toolkit.connection.connectedAccount) {
128 + console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount.id}`);
129 + }
130 +}
131 +```
132 +</Tab>
133 +</Tabs>
fumadocs/content/tool-router/manually-authenticating-users.mdx new
+162
@@ -0,0 +1,162 @@
1 +---
2 +title: Manually authenticating users
3 +description: Authenticate users to toolkits outside of chat
4 +---
5 +
6 +Manual authentication lets you connect users to toolkits outside of the chat flow. Use this when you want to:
7 +- Pre-authenticate users before they start chatting
8 +- Build a custom connections UI in your app
9 +
10 +## Authorize a toolkit
11 +
12 +Use `session.authorize()` to generate a [Connect Link](/docs/authenticating-tools#hosted-authentication-connect-link) URL, redirect the user, and wait for them to complete:
13 +
14 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
15 +<Tab value="Python">
16 +```python
17 +session = composio.create(user_id="user_123")
18 +
19 +connection_request = session.authorize("gmail")
20 +
21 +print(connection_request.redirect_url)
22 +# https://connect.composio.dev/link/ln_abc123
23 +
24 +connected_account = connection_request.wait_for_connection(60000)
25 +print(f"Connected: {connected_account.id}")
26 +```
27 +</Tab>
28 +<Tab value="TypeScript">
29 +```typescript
30 +const session = await composio.create("user_123");
31 +
32 +const connectionRequest = await session.authorize("gmail");
33 +
34 +console.log(connectionRequest.redirectUrl);
35 +// https://connect.composio.dev/link/ln_abc123
36 +
37 +const connectedAccount = await connectionRequest.waitForConnection(60000);
38 +console.log(`Connected: ${connectedAccount.id}`);
39 +```
40 +</Tab>
41 +</Tabs>
42 +
43 +Redirect the user to the redirect URL. After they authenticate, they'll return to your callback URL. The connection request polls until the user completes authentication (default timeout: 60 seconds).
44 +
45 +<Callout type="info">
46 +If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.
47 +</Callout>
48 +
49 +## Check connection status
50 +
51 +Use `session.toolkits()` to see all toolkits in the session and their connection status:
52 +
53 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
54 +<Tab value="Python">
55 +```python
56 +toolkits = session.toolkits()
57 +
58 +for toolkit in toolkits.items:
59 + status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
60 + print(f"{toolkit.name}: {status}")
61 +```
62 +</Tab>
63 +<Tab value="TypeScript">
64 +```typescript
65 +const toolkits = await session.toolkits();
66 +
67 +toolkits.items.forEach((toolkit) => {
68 + console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount?.id ?? "Not connected"}`);
69 +});
70 +```
71 +</Tab>
72 +</Tabs>
73 +
74 +## Disabling in-chat auth
75 +
76 +By default, Tool Router includes the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool that prompts users to authenticate during chat. To disable this and handle auth entirely in your UI:
77 +
78 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
79 +<Tab value="Python">
80 +```python
81 +session = composio.create(
82 + user_id="user_123",
83 + manage_connections=False,
84 +)
85 +```
86 +</Tab>
87 +<Tab value="TypeScript">
88 +```typescript
89 +const session = await composio.create("user_123", {
90 + manageConnections: false,
91 +});
92 +```
93 +</Tab>
94 +</Tabs>
95 +
96 +## Putting it together
97 +
98 +A common pattern is to verify all required connections before starting the agent:
99 +
100 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
101 +<Tab value="Python">
102 +```python
103 +from composio import Composio
104 +
105 +composio = Composio(api_key="your-api-key")
106 +
107 +required_toolkits = ["gmail", "github"]
108 +
109 +session = composio.create(
110 + user_id="user_123",
111 + manage_connections=False, # Disable in-chat auth prompts
112 +)
113 +
114 +toolkits = session.toolkits()
115 +
116 +connected = {t.slug for t in toolkits.items if t.connection.is_active}
117 +pending = [slug for slug in required_toolkits if slug not in connected]
118 +
119 +print(f"Connected: {connected}")
120 +print(f"Pending: {pending}")
121 +
122 +for slug in pending:
123 + connection_request = session.authorize(slug)
124 + print(f"Connect {slug}: {connection_request.redirect_url}")
125 + connection_request.wait_for_connection()
126 +
127 +print(f"All toolkits connected! MCP URL: {session.mcp.url}")
128 +```
129 +</Tab>
130 +<Tab value="TypeScript">
131 +```typescript
132 +import { Composio } from "@composio/core";
133 +
134 +const composio = new Composio({ apiKey: "your-api-key" });
135 +
136 +const requiredToolkits = ["gmail", "github"];
137 +
138 +const session = await composio.create("user_123", {
139 + manageConnections: false, // Disable in-chat auth prompts
140 +});
141 +
142 +const toolkits = await session.toolkits();
143 +
144 +const connected = toolkits.items
145 + .filter((t) => t.connection.connectedAccount)
146 + .map((t) => t.slug);
147 +
148 +const pending = requiredToolkits.filter((slug) => !connected.includes(slug));
149 +
150 +console.log("Connected:", connected);
151 +console.log("Pending:", pending);
152 +
153 +for (const slug of pending) {
154 + const connectionRequest = await session.authorize(slug);
155 + console.log(`Connect ${slug}: ${connectionRequest.redirectUrl}`);
156 + await connectionRequest.waitForConnection();
157 +}
158 +
159 +console.log(`All toolkits connected! MCP URL: ${session.mcp.url}`);
160 +```
161 +</Tab>
162 +</Tabs>
fumadocs/content/tool-router/meta.json
+16 -1
@@ -2,6 +2,21 @@
2 "title": "Tool Router",
3 "pages": [
4 "---Get Started---",
5 - "index"
5 + "index",
6 + "quickstart",
7 + "---Core Concepts---",
8 + "users-and-sessions",
9 + "authentication",
10 + "tools-and-toolkits",
11 + "---Guides---",
12 + "using-in-chat-authentication",
13 + "manually-authenticating-users",
14 + "managing-multiple-accounts",
15 + "white-labeling-authentication",
16 + "using-custom-auth-configs",
17 + "using-with-mcp-clients",
18 + "using-as-a-native-tool",
19 + "---Resources---",
20 + "migration-guide"
21 ]
22 }
fumadocs/content/tool-router/migration-guide/beta-to-stable.mdx new
+108
@@ -0,0 +1,108 @@
1 +---
2 +title: Beta to Stable Migration
3 +description: Migrate from Tool Router beta to the stable version
4 +---
5 +
6 +The stable version includes improved session management, multiple configuring options, and enhanced authentication capabilities.
7 +
8 +## The basics
9 +
10 +<Steps>
11 +<Step>
12 +### Upgrade composio package
13 +
14 +Upgrade to the latest stable version:
15 +
16 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
17 +<Tab value="Python">
18 +```bash
19 +pip install --upgrade composio
20 +```
21 +</Tab>
22 +<Tab value="TypeScript">
23 +```bash
24 +npm install @composio/core@latest
25 +```
26 +</Tab>
27 +</Tabs>
28 +</Step>
29 +
30 +<Step>
31 +### Update session creation
32 +
33 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
34 +<Tab value="Python">
35 +```python
36 +# Beta (before)
37 +session = composio.experimental.tool_router.create_session(
38 + user_id="user@example.com"
39 +)
40 +
41 +# Stable (after)
42 +session = composio.create(
43 + user_id="user@example.com"
44 +)
45 +```
46 +</Tab>
47 +<Tab value="TypeScript">
48 +```typescript
49 +// Beta (before)
50 +const session = await composio.experimental.toolRouter.createSession('user_123');
51 +
52 +// Stable (after)
53 +const session = await composio.create('user_123');
54 +```
55 +</Tab>
56 +</Tabs>
57 +</Step>
58 +
59 +<Step>
60 +### Moving users (optional)
61 +
62 +If you have existing users on tool router and you don't want them to authenticate again:
63 +- Tool Router will auto-detect auth configs and connected accounts it created (from the beta version).
64 +- If you have custom auth configs (not created by Tool Router):
65 + - Search for the Auth config for that connected account. See [Connected Accounts](/docs/connected-accounts) to fetch existing accounts programmatically.
66 + - While creating a session configure to use this Auth config.
67 + - You need to repeat this for each toolkit you want to enable for that session.
68 +
69 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
70 +<Tab value="Python">
71 +```python
72 +session = composio.create(
73 + user_id="user_123",
74 + auth_configs={
75 + "github": "ac_your_github_config",
76 + "slack": "ac_your_slack_config"
77 + }
78 +)
79 +```
80 +</Tab>
81 +<Tab value="TypeScript">
82 +```typescript
83 +const session = await composio.create('user_123',
84 + {
85 + authConfigs: {
86 + github: "ac_your_github_config",
87 + slack: "ac_your_slack_config",
88 + },
89 + }
90 +);
91 +```
92 +</Tab>
93 +</Tabs>
94 +</Step>
95 +
96 +<Step>
97 +### Explore new capabilities
98 +
99 +Check out these new features available in the stable version:
100 +
101 +- **[Native tools](/tool-router/using-as-a-native-tool)**: Use Tool Router with any AI framework
102 +- **Better [session](/tool-router/users-and-sessions) and [auth](/tool-router/authentication) config**
103 +- **[Multi-account support](/tool-router/managing-multiple-accounts)**: Manage multiple accounts per user seamlessly
104 +- **[Manual authentication](/tool-router/manually-authenticating-users)**: Control when and how users authenticate
105 +- **[Custom auth](/tool-router/using-custom-auth-configs)**: Support for toolkits that don't have composio managed auth
106 +- **[White labeling](/tool-router/white-labeling-authentication)**: Customize authentication screens with your branding
107 +</Step>
108 +</Steps>
fumadocs/content/tool-router/migration-guide/meta.json new
+6
@@ -0,0 +1,6 @@
1 +{
2 + "title": "Migration Guides",
3 + "pages": [
4 + "beta-to-stable"
5 + ]
6 +}
fumadocs/content/tool-router/quickstart.mdx new
+704
@@ -0,0 +1,704 @@
1 +---
2 +title: Quickstart
3 +description: Build an AI agent with access to 1000+ tools
4 +---
5 +
6 +Choose how you want to integrate Tool Router:
7 +
8 +<Accordions>
9 +<Accordion title="Using Tool Router MCP">
10 +
11 +<Tabs items={['Claude Agent SDK', 'OpenAI Agents SDK', 'Vercel AI SDK']}>
12 +<Tab value="Claude Agent SDK">
13 +
14 +<Steps>
15 +<Step>
16 +### Install
17 +
18 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 +<Tab value="Python">
20 +```bash
21 +pip install python-dotenv composio claude-agent-sdk
22 +```
23 +</Tab>
24 +<Tab value="TypeScript">
25 +```bash
26 +npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk
27 +```
28 +</Tab>
29 +</Tabs>
30 +</Step>
31 +
32 +<Step>
33 +### Create session and run agent
34 +
35 +[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
36 +
37 +<Callout type="info">
38 +- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
39 +- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).
40 +- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.
41 +</Callout>
42 +
43 +When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
44 +
45 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
46 +<Tab value="Python">
47 +```python
48 +import asyncio
49 +from dotenv import load_dotenv
50 +from claude_agent_sdk.client import ClaudeSDKClient
51 +from claude_agent_sdk.types import (
52 + ClaudeAgentOptions,
53 + AssistantMessage,
54 + TextBlock,
55 + ToolUseBlock,
56 +)
57 +from composio import Composio
58 +
59 +load_dotenv()
60 +
61 +# Initialize Composio (API key from env var COMPOSIO_API_KEY)
62 +composio = Composio()
63 +
64 +# Unique identifier of the user
65 +user_id = "user_123"
66 +
67 +# Create a tool router session for the user
68 +session = composio.create(user_id=user_id)
69 +
70 +# Configure Claude with Composio MCP server
71 +options = ClaudeAgentOptions(
72 + system_prompt=(
73 + "You are a helpful assistant with access to external tools. "
74 + "Always use the available tools to complete user requests."
75 + ),
76 + mcp_servers={
77 + "composio": {
78 + "type": "http",
79 + "url": session.mcp.url,
80 + "headers": session.mcp.headers,
81 + }
82 + },
83 + permission_mode="bypassPermissions",
84 +)
85 +
86 +
87 +async def main():
88 + print("""
89 +What task would you like me to help you with?
90 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
91 +(Type 'exit' to exit)
92 +Example tasks:
93 + • 'Summarize my emails from today'
94 + • 'List all open issues on the composio github repository and create a notion page with the issues'
95 +""")
96 +
97 + async with ClaudeSDKClient(options) as client:
98 + # Multi-turn conversation with agentic tool calling
99 + while True:
100 + user_input = input("You: ").strip()
101 + if user_input.lower() == "exit":
102 + break
103 +
104 + print("\nClaude: ", end="", flush=True)
105 + try:
106 + await client.query(user_input)
107 + async for msg in client.receive_response():
108 + if isinstance(msg, AssistantMessage):
109 + for block in msg.content:
110 + if isinstance(block, ToolUseBlock):
111 + print(f"\n[Using tool: {block.name}]", end="")
112 + elif isinstance(block, TextBlock):
113 + print(block.text, end="", flush=True)
114 + print()
115 + except Exception as e:
116 + print(f"\n[Error]: {e}")
117 +
118 +
119 +if __name__ == "__main__":
120 + asyncio.run(main())
121 +```
122 +</Tab>
123 +<Tab value="TypeScript">
124 +```typescript
125 +import "dotenv/config";
126 +import { query, type Options } from "@anthropic-ai/claude-agent-sdk";
127 +import { Composio } from "@composio/core";
128 +import { createInterface } from "readline/promises";
129 +
130 +// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
131 +const composio = new Composio();
132 +
133 +// Unique identifier of the user
134 +const userId = "user_123";
135 +
136 +// Create a tool router session for the user
137 +const session = await composio.create(userId);
138 +
139 +const options: Options = {
140 + systemPrompt: `You are a helpful assistant with access to external tools. ` +
141 + `Always use the available tools to complete user requests.`,
142 + mcpServers: {
143 + composio: {
144 + type: "http",
145 + url: session.mcp.url,
146 + headers: session.mcp.headers // Authentication headers for the Composio MCP server
147 + },
148 + },
149 + permissionMode: "bypassPermissions", // Auto-approve tools (demo only - use "default" in production)
150 +};
151 +
152 +// Set up interactive terminal input/output for the conversation
153 +const readline = createInterface({ input: process.stdin, output: process.stdout });
154 +
155 +console.log(`
156 +What task would you like me to help you with?
157 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
158 +(Type 'exit' to exit)
159 +Example tasks:
160 + • 'Summarize my emails from today'
161 + • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
162 +`);
163 +
164 +let isFirstQuery = true;
165 +
166 +// Multi-turn conversation with agentic tool calling
167 +while (true) {
168 + const answer = await readline.question('You: ');
169 + const input = answer.trim();
170 + if (input.toLowerCase() === "exit") break;
171 +
172 + process.stdout.write("Claude: ");
173 +
174 + // Use `continue: true` to maintain conversation context
175 + const queryOptions = isFirstQuery ? options : { ...options, continue: true };
176 + isFirstQuery = false;
177 +
178 + try {
179 + for await (const stream of query({ prompt: input, options: queryOptions })) {
180 + // Only process assistant messages (the SDK also sends result/error messages)
181 + if (stream.type === "assistant") {
182 + const { content } = stream.message;
183 + for (const block of content) {
184 + if (block.type === "tool_use") {
185 + process.stdout.write(`\n[Using tool: ${block.name}]`);
186 + } else if (block.type === "text") {
187 + process.stdout.write(block.text);
188 + }
189 + }
190 + }
191 + }
192 + } catch (error) {
193 + console.error("\n[Error]:", error instanceof Error ? error.message : error);
194 + }
195 + process.stdout.write("\n");
196 +}
197 +
198 +readline.close();
199 +```
200 +</Tab>
201 +</Tabs>
202 +</Step>
203 +</Steps>
204 +
205 +</Tab>
206 +
207 +<Tab value="OpenAI Agents SDK">
208 +
209 +<Steps>
210 +<Step>
211 +### Install
212 +
213 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
214 +<Tab value="Python">
215 +```bash
216 +pip install python-dotenv composio openai-agents
217 +```
218 +</Tab>
219 +<Tab value="TypeScript">
220 +```bash
221 +npm install dotenv @composio/core @openai/agents zod@3
222 +```
223 +</Tab>
224 +</Tabs>
225 +</Step>
226 +
227 +<Step>
228 +### Create session and run agent
229 +
230 +[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
231 +
232 +<Callout type="info">
233 +- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
234 +- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
235 +- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.
236 +</Callout>
237 +
238 +When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
239 +
240 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
241 +<Tab value="Python">
242 +```python
243 +from dotenv import load_dotenv
244 +from composio import Composio
245 +from agents import Agent, Runner, HostedMCPTool, SQLiteSession
246 +
247 +load_dotenv()
248 +
249 +# Initialize Composio (API key from env var COMPOSIO_API_KEY)
250 +composio = Composio()
251 +
252 +# Unique identifier of the user
253 +user_id = "user_123"
254 +
255 +# Create a Tool Router session for the user
256 +session = composio.create(user_id=user_id)
257 +
258 +# Configure OpenAI agent with Composio MCP server
259 +agent = Agent(
260 + name="Personal Assistant",
261 + instructions="You are a helpful personal assistant. Use Composio tools to take action.",
262 + model="gpt-5.2",
263 + tools=[
264 + HostedMCPTool(
265 + tool_config={
266 + "type": "mcp",
267 + "server_label": "composio",
268 + "server_url": session.mcp.url,
269 + "require_approval": "never",
270 + "headers": session.mcp.headers,
271 + }
272 + )
273 + ],
274 +)
275 +
276 +# Memory for multi-turn conversation
277 +memory = SQLiteSession(user_id)
278 +
279 +print("""
280 +What task would you like me to help you with?
281 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
282 +(Type 'exit' to exit)
283 +Example tasks:
284 + • 'Summarize my emails from today'
285 + • 'List all open issues on the composio github repository'
286 +""")
287 +
288 +while True:
289 + user_input = input("You: ").strip()
290 + if user_input.lower() == "exit":
291 + break
292 +
293 + print("Assistant: ", end="", flush=True)
294 + try:
295 + result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
296 + print(f"{result.final_output}\n")
297 + except Exception as e:
298 + print(f"\n[Error]: {e}")
299 +```
300 +</Tab>
301 +<Tab value="TypeScript">
302 +```typescript
303 +import "dotenv/config";
304 +import { Composio } from "@composio/core";
305 +import { Agent, run, hostedMcpTool, MemorySession } from "@openai/agents";
306 +import { createInterface } from "readline/promises";
307 +
308 +// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
309 +const composio = new Composio();
310 +
311 +// Unique identifier of the user
312 +const userId = "user_123";
313 +
314 +// Create a tool router session for the user
315 +const session = await composio.create(userId);
316 +
317 +const agent = new Agent({
318 + name: "Personal Assistant",
319 + instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
320 + model: "gpt-5.2",
321 + tools: [
322 + hostedMcpTool({
323 + serverLabel: "composio",
324 + serverUrl: session.mcp.url,
325 + headers: session.mcp.headers // Authentication headers for the Composio MCP server
326 + }),
327 + ],
328 +});
329 +
330 +// Create a memory session for persistent multi-turn conversation
331 +const memory = new MemorySession();
332 +
333 +// Set up interactive terminal input/output for the conversation
334 +const readline = createInterface({ input: process.stdin, output: process.stdout });
335 +
336 +console.log(`
337 +What task would you like me to help you with?
338 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
339 +(Type 'exit' to exit)
340 +Example tasks:
341 + • 'Summarize my emails from today'
342 + • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
343 +`);
344 +
345 +// Multi-turn conversation with agentic tool calling
346 +while (true) {
347 + const input = (await readline.question("You: ")).trim();
348 + if (input.toLowerCase() === "exit") break;
349 +
350 + console.log("Assistant: ");
351 +
352 + try {
353 + // Multi-turn agentic loop: GPT calls tools and reasons until task is complete
354 + const result = await run(agent, input, { session: memory });
355 + console.log(`${result.finalOutput}`);
356 + } catch (error) {
357 + console.error("\n[Error]:", error instanceof Error ? error.message : error);
358 + }
359 +}
360 +readline.close();
361 +```
362 +</Tab>
363 +</Tabs>
364 +</Step>
365 +</Steps>
366 +
367 +</Tab>
368 +
369 +<Tab value="Vercel AI SDK">
370 +
371 +<Steps>
372 +<Step>
373 +### Install Composio SDK
374 +
375 +```bash
376 +npm install dotenv @composio/core ai @ai-sdk/anthropic @ai-sdk/mcp
377 +```
378 +</Step>
379 +
380 +<Step>
381 +### Create session and run agent
382 +
383 +[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.
384 +
385 +<Callout type="info">
386 +- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
387 +- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).
388 +- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.
389 +</Callout>
390 +
391 +When the agent needs authentication, it will prompt the user with a link to connect their account. If you want to customise the authentication flow and have more control over the user experience, see [Manual Authentication](/tool-router/manually-authenticating-users).
392 +
393 +```typescript
394 +import "dotenv/config";
395 +import { anthropic } from "@ai-sdk/anthropic";
396 +import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
397 +import { Composio } from "@composio/core";
398 +import { stepCountIs, streamText } from "ai";
399 +
400 +// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
401 +const composio = new Composio();
402 +
403 +// Unique identifier of the user
404 +const userId = "user_123";
405 +
406 +// Create a tool router session for the user
407 +const { mcp } = await composio.create(userId);
408 +
409 +// Create an MCP client to connect to the Composio tool router
410 +const client = await createMCPClient({
411 + transport: {
412 + type: "http",
413 + url: mcp.url,
414 + headers: mcp.headers, // Authentication headers for the Composio MCP server
415 + },
416 +});
417 +const tools = await client.tools();
418 +
419 +console.log("Summarizing your emails from today");
420 +
421 +const stream = await streamText({
422 + system: "You are a helpful personal assistant. Use Composio tools to take action.",
423 + model: anthropic("claude-sonnet-4-5"),
424 + prompt: "Summarize my emails from today",
425 + stopWhen: stepCountIs(10),
426 + onStepFinish: (step) => {
427 + for (const toolCall of step.toolCalls) {
428 + console.log(`[Using tool: ${toolCall.toolName}]`);
429 + }
430 + },
431 + tools,
432 +});
433 +
434 +for await (const textPart of stream.textStream) {
435 + process.stdout.write(textPart);
436 +}
437 +
438 +console.log("\n\n---");
439 +console.log("Tip: If prompted to authenticate, complete the auth flow and run again.");
440 +```
441 +</Step>
442 +</Steps>
443 +
444 +</Tab>
445 +</Tabs>
446 +
447 +### What just happened?
448 +
449 +When you run this agent, Tool Router:
450 +1. **Creates an MCP server** with your session configuration
451 +2. **Searches** for the right tools based on your request
452 +3. **Handles authentication** if needed
453 +4. **Executes tools** and uses a workbench for processing large responses
454 +
455 +</Accordion>
456 +
457 +<Accordion title="Using Tool router as a native tool">
458 +
459 +<Tabs items={['OpenAI', 'Vercel AI SDK']}>
460 +<Tab value="OpenAI">
461 +
462 +<Steps>
463 +<Step>
464 +### Install
465 +
466 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
467 +<Tab value="Python">
468 +```bash
469 +pip install python-dotenv composio composio-openai-agents openai-agents
470 +```
471 +</Tab>
472 +<Tab value="TypeScript">
473 +```bash
474 +npm install @composio/core @composio/openai-agents @openai/agents
475 +```
476 +</Tab>
477 +</Tabs>
478 +</Step>
479 +
480 +<Step>
481 +### Create session and use as native tool
482 +
483 +Tool Router can be added as a single native tool to your agent. This provides a meta-tool that handles search, authentication, and execution across all 1000+ Composio tools.
484 +
485 +<Callout type="info">
486 +- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
487 +- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
488 +- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.
489 +</Callout>
490 +
491 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
492 +<Tab value="Python">
493 +```python
494 +from dotenv import load_dotenv
495 +from composio import Composio
496 +from agents import Agent, Runner, SQLiteSession
497 +from composio_openai_agents import OpenAIAgentsProvider
498 +
499 +load_dotenv()
500 +
501 +# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
502 +composio = Composio(provider=OpenAIAgentsProvider())
503 +
504 +# Unique identifier of the user
505 +user_id = "user_123"
506 +
507 +# Create a session and get native tools for the user
508 +session = composio.create(user_id=user_id)
509 +tools = session.tools()
510 +
511 +# Configure OpenAI agent with Composio tools
512 +agent = Agent(
513 + name="Personal Assistant",
514 + instructions="You are a helpful personal assistant. Use Composio tools to take action.",
515 + model="gpt-5.2",
516 + tools=tools,
517 +)
518 +
519 +# Memory for multi-turn conversation
520 +memory = SQLiteSession("conversation")
521 +
522 +print("""
523 +What task would you like me to help you with?
524 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
525 +(Type 'exit' to exit)
526 +Example tasks:
527 + • 'Summarize my emails from today'
528 + • 'List all open issues on the composio github repository'
529 +""")
530 +
531 +while True:
532 + user_input = input("You: ").strip()
533 + if user_input.lower() == "exit":
534 + break
535 +
536 + print("Assistant: ", end="", flush=True)
537 + try:
538 + result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
539 + print(f"{result.final_output}\n")
540 + except Exception as e:
541 + print(f"\n[Error]: {e}")
542 +```
543 +</Tab>
544 +<Tab value="TypeScript">
545 +```typescript
546 +import "dotenv/config";
547 +import { Composio } from "@composio/core";
548 +import { Agent, run, MemorySession } from "@openai/agents";
549 +import { OpenAIAgentsProvider } from "@composio/openai-agents";
550 +import { createInterface } from "readline/promises";
551 +
552 +// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
553 +const composio = new Composio({ provider: new OpenAIAgentsProvider() });
554 +
555 +// Unique identifier of the user
556 +const userId = "user_123";
557 +// Create a tool router session for the user
558 +const session = await composio.create(userId);
559 +const tools = await session.tools();
560 +
561 +const agent = new Agent({
562 + name: "Personal Assistant",
563 + instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
564 + model: "gpt-5.2",
565 + tools,
566 +});
567 +
568 +// Set up interactive terminal input/output for the conversation
569 +const readline = createInterface({ input: process.stdin, output: process.stdout });
570 +// Create a memory session for persistent multi-turn conversation
571 +const memory = new MemorySession();
572 +
573 +console.log(`
574 +What task would you like me to help you with?
575 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
576 +(Type 'exit' to exit)
577 +Example tasks:
578 + • 'Summarize my emails from today'
579 + • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
580 +`);
581 +
582 +// Multi-turn conversation with agentic tool calling
583 +while (true) {
584 + const query = await readline.question("You: ");
585 + const input = query.trim();
586 +
587 + if (input.toLowerCase() === "exit") break;
588 + process.stdout.write("Assistant: ");
589 +
590 + try {
591 + const result = await run(agent, input, { session: memory });
592 + process.stdout.write(`${result.finalOutput}`);
593 + } catch (error) {
594 + console.error("\n[Error]:", error instanceof Error ? error.message : error);
595 + }
596 +}
597 +readline.close();
598 +```
599 +</Tab>
600 +</Tabs>
601 +</Step>
602 +</Steps>
603 +
604 +</Tab>
605 +
606 +<Tab value="Vercel AI SDK">
607 +
608 +<Steps>
609 +<Step>
610 +### Install
611 +
612 +```bash
613 +npm install @composio/core @composio/vercel ai @ai-sdk/anthropic
614 +```
615 +</Step>
616 +
617 +<Step>
618 +### Create session and use as native tool
619 +
620 +Tool Router can be added as a single native tool to your agent. This provides a meta-tool that handles search, authentication, and execution across all 1000+ Composio tools.
621 +
622 +<Callout type="info">
623 +- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
624 +- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://console.anthropic.com/settings/keys).
625 +- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.
626 +</Callout>
627 +
628 +```typescript
629 +import "dotenv/config";
630 +import { anthropic } from "@ai-sdk/anthropic";
631 +import { Composio } from "@composio/core";
632 +import { VercelProvider } from "@composio/vercel";
633 +import { stepCountIs, streamText } from "ai";
634 +
635 +// Initialize Composio with Vercel provider (API key from env var COMPOSIO_API_KEY)
636 +const composio = new Composio({ provider: new VercelProvider() });
637 +
638 +// Unique identifier of the user
639 +const userId = "user_123";
640 +
641 +// Create a session and get native tools for the user
642 +const session = await composio.create(userId);
643 +const tools = await session.tools();
644 +
645 +process.stdout.write("Summarizing your emails from today");
646 +process.stdout.write("\n");
647 +
648 +const stream = await streamText({
649 + system: "You are a helpful personal assistant. Use Composio tools to take action.",
650 + model: anthropic("claude-sonnet-4-5"),
651 + prompt: "Summarize my emails from today",
652 + stopWhen: stepCountIs(10),
653 + onStepFinish: (step) => {
654 + for (const toolCall of step.toolCalls) {
655 + process.stdout.write(`[Using tool: ${toolCall.toolName}]`);
656 + process.stdout.write("\n");
657 + }
658 + },
659 + tools,
660 +});
661 +
662 +for await (const textPart of stream.textStream) {
663 + process.stdout.write(textPart);
664 +}
665 +
666 +process.stdout.write("\n");
667 +process.stdout.write("Tip: If prompted to authenticate, complete the auth flow and run again.");
668 +```
669 +</Step>
670 +</Steps>
671 +
672 +</Tab>
673 +</Tabs>
674 +
675 +### What just happened?
676 +
677 +When you run this agent, Tool Router:
678 +1. **Provides a single tool** to your agent framework
679 +2. **Interprets requests** and **searches** for the right tools internally
680 +3. **Handles authentication** if needed
681 +4. **Executes tools** and uses a workbench for processing large responses
682 +
683 +</Accordion>
684 +</Accordions>
685 +
686 +## Next steps
687 +
688 +<Cards>
689 + <Card title="Session management" href="/tool-router/users-and-sessions">
690 + Learn about users, sessions, and how they work.
691 + </Card>
692 + <Card title="Tools and toolkits" href="/tool-router/tools-and-toolkits">
693 + Learn about tools, toolkits, and how to configure them.
694 + </Card>
695 + <Card title="Manual authentication" href="/tool-router/manually-authenticating-users">
696 + Customise the authentication flow for your users.
697 + </Card>
698 + <Card title="Using MCP" href="/tool-router/using-with-mcp-clients">
699 + Connect Tool Router to any MCP-compatible client.
700 + </Card>
701 + <Card title="Using as a native tool" href="/tool-router/using-as-a-native-tool">
702 + Use Tool Router as a native tool with any AI framework.
703 + </Card>
704 +</Cards>
fumadocs/content/tool-router/tools-and-toolkits.mdx new
+77
@@ -0,0 +1,77 @@
1 +---
2 +title: Tools and toolkits
3 +description: Access 800+ integrations through Tool Router
4 +---
5 +
6 +Tool Router gives your agent access to most Composio toolkits by default. For details on configuring which toolkits are available in a session, see [Users and sessions](/tool-router/users-and-sessions#enabling-toolkits).
7 +
8 +## Toolkits and tools
9 +
10 +A **toolkit** is a collection of related tools for a service and a **tool** is an individual action your agent can execute.
11 +
12 +| Toolkit | Tools |
13 +|---------|-------|
14 +| `github` | `GITHUB_CREATE_A_COMMIT`, `GITHUB_ACTIVITY_LIST_STARGAZERS_FOR_REPO`, `GITHUB_SEARCH_REPO_S`, ... |
15 +| `gmail` | `GMAIL_SEND_EMAIL`, `GMAIL_FETCH_EMAILS`, `GMAIL_CREATE_EMAIL_DRAFT`, ... |
16 +| `linear` | `LINEAR_CREATE_LINEAR_ISSUE`, `LINEAR_UPDATE_ISSUE`, `LINEAR_CREATE_LINEAR_LABEL`, ... |
17 +
18 +## Available toolkits
19 +
20 +Browse all available toolkits in the [Composio platform](https://platform.composio.dev) under "All Toolkits". Each toolkit page shows its tools (with input and output parameters) and authentication methods supported for that toolkit.
21 +
22 +You can also list toolkits programmatically:
23 +
24 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
25 +<Tab value="Python">
26 +```python
27 +# Returns top 20 toolkits by default
28 +toolkits = composio.toolkits.get()
29 +
30 +for toolkit in toolkits:
31 + print(toolkit.name)
32 +```
33 +</Tab>
34 +<Tab value="TypeScript">
35 +```typescript
36 +// Returns top 20 toolkits by default
37 +const toolkits = await composio.toolkits.get();
38 +
39 +for (const toolkit of toolkits) {
40 + console.log(toolkit.name);
41 +}
42 +```
43 +</Tab>
44 +</Tabs>
45 +
46 +For details on browsing tools within toolkits and inspecting schemas, see [Fetching tools and schemas](/docs/fetching-tools).
47 +
48 +<Callout type="info">
49 +Some toolkits require you to provide your own credentials. See [Using custom auth configs](/tool-router/using-custom-auth-configs).
50 +</Callout>
51 +
52 +<Callout type="info">
53 +Need a toolkit that doesn't exist? [Request it here](https://request.composio.dev/boards/tool-requests).
54 +</Callout>
55 +
56 +## Default session behavior
57 +
58 +When you create a session, all toolkits are available:
59 +
60 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
61 +<Tab value="Python">
62 +```python
63 +session = composio.create(user_id="user_123")
64 +```
65 +</Tab>
66 +<Tab value="TypeScript">
67 +```typescript
68 +const session = await composio.create("user_123");
69 +```
70 +</Tab>
71 +</Tabs>
72 +
73 +Your agent can search and use tools from any toolkit. To restrict or configure which toolkits are available, see [Users and sessions](/tool-router/users-and-sessions#enabling-toolkits).
74 +
75 +<Callout type="info">
76 +Triggers can be used alongside Tool Router to respond to events in connected apps. See [Using triggers](/docs/using-triggers) for setup instructions.
77 +</Callout>
fumadocs/content/tool-router/users-and-sessions.mdx new
+254
@@ -0,0 +1,254 @@
1 +---
2 +title: Users and sessions
3 +description: Understand how Tool Router scopes tools and connections per user
4 +---
5 +
6 +A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. User IDs can represent individuals, teams, or organizations. See [User Management](/docs/user-management) for patterns.
7 +
8 +A **session** is an ephemeral configuration that combines:
9 +- Which user's connected accounts to use
10 +- Which toolkits are available
11 +- Which auth configs to use
12 +
13 +Tool Router's meta-tools are the same for everyone. The session determines the context they operate within.
14 +
15 +## Creating a session
16 +
17 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
18 +<Tab value="Python">
19 +```python
20 +session = composio.create(user_id="user_123")
21 +```
22 +</Tab>
23 +<Tab value="TypeScript">
24 +```typescript
25 +const session = await composio.create("user_123");
26 +```
27 +</Tab>
28 +</Tabs>
29 +
30 +### Enabling toolkits
31 +
32 +Restrict the session to specific toolkits:
33 +
34 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
35 +<Tab value="Python">
36 +```python
37 +# Using array format
38 +session = composio.create(
39 + user_id="user_123",
40 + toolkits=["github", "gmail", "slack"]
41 +)
42 +
43 +# Using object format with enable key
44 +session = composio.create(
45 + user_id="user_123",
46 + toolkits={"enable": ["github", "gmail", "slack"]}
47 +)
48 +```
49 +</Tab>
50 +<Tab value="TypeScript">
51 +```typescript
52 +// Using array format
53 +const session = await composio.create("user_123", {
54 + toolkits: ["github", "gmail", "slack"],
55 +});
56 +
57 +// Using object format with enable key
58 +const session = await composio.create("user_123", {
59 + toolkits: { enable: ["github", "gmail", "slack"] },
60 +});
61 +```
62 +</Tab>
63 +</Tabs>
64 +
65 +### Disabling toolkits
66 +
67 +Keep all toolkits enabled except specific ones:
68 +
69 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
70 +<Tab value="Python">
71 +```python
72 +session = composio.create(
73 + user_id="user_123",
74 + toolkits={"disable": ["exa", "firecrawl"]}
75 +)
76 +```
77 +</Tab>
78 +<Tab value="TypeScript">
79 +```typescript
80 +const session = await composio.create("user_123", {
81 + toolkits: { disable: ["exa", "firecrawl"] },
82 +});
83 +```
84 +</Tab>
85 +</Tabs>
86 +
87 +### Custom auth configs
88 +
89 +Use your own OAuth credentials instead of Composio's defaults:
90 +
91 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
92 +<Tab value="Python">
93 +```python
94 +session = composio.create(
95 + user_id="user_123",
96 + auth_configs={
97 + "github": "ac_your_github_config",
98 + "slack": "ac_your_slack_config"
99 + }
100 +)
101 +```
102 +</Tab>
103 +<Tab value="TypeScript">
104 +```typescript
105 +const session = await composio.create("user_123", {
106 + authConfigs: {
107 + github: "ac_your_github_config",
108 + slack: "ac_your_slack_config",
109 + },
110 +});
111 +```
112 +</Tab>
113 +</Tabs>
114 +
115 +See [White-labeling authentication](/tool-router/white-labeling-authentication) for branding, or [Using custom auth configs](/tool-router/using-custom-auth-configs) for toolkits that require your own credentials.
116 +
117 +## Connected accounts
118 +
119 +Connected accounts are stored in Composio and persist across sessions. When a user connects their GitHub account in one session, it remains available in future sessions. Sessions configure *which* connections to use, but don't own the connections themselves.
120 +
121 +### Account selection
122 +
123 +If a user has multiple connected accounts for the same toolkit, you can specify which one to use:
124 +
125 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
126 +<Tab value="Python">
127 +```python
128 +session = composio.create(
129 + user_id="user_123",
130 + connected_accounts={
131 + "gmail": "ca_work_gmail",
132 + "github": "ca_personal_github"
133 + }
134 +)
135 +```
136 +</Tab>
137 +<Tab value="TypeScript">
138 +```typescript
139 +const session = await composio.create("user_123", {
140 + connectedAccounts: {
141 + gmail: "ca_work_gmail",
142 + github: "ca_personal_github",
143 + },
144 +});
145 +```
146 +</Tab>
147 +</Tabs>
148 +
149 +### Precedence
150 +
151 +When executing a tool, Tool Router selects the connected account in this order:
152 +
153 +1. `connectedAccounts` override if provided in session config
154 +2. `authConfigs` override - finds or creates connection on that config
155 +3. Auth config previously created by Tool Router for this toolkit
156 +4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
157 +5. Error if no Composio managed auth scheme exists for the toolkit
158 +
159 +If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
160 +
161 +## Session methods
162 +
163 +### mcp
164 +
165 +Get the MCP server URL to use with any MCP-compatible client.
166 +
167 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
168 +<Tab value="Python">
169 +```python
170 +mcp_url = session.mcp.url
171 +```
172 +</Tab>
173 +<Tab value="TypeScript">
174 +```typescript
175 +const { mcp } = session;
176 +console.log(mcp.url);
177 +```
178 +</Tab>
179 +</Tabs>
180 +
181 +For framework examples, see [Using with MCP clients](/tool-router/using-with-mcp-clients) or [Using as a native tool](/tool-router/using-as-a-native-tool).
182 +
183 +### tools()
184 +
185 +Get native tools from the session for use with AI frameworks.
186 +
187 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
188 +<Tab value="Python">
189 +```python
190 +tools = session.tools()
191 +```
192 +</Tab>
193 +<Tab value="TypeScript">
194 +```typescript
195 +const tools = await session.tools();
196 +```
197 +</Tab>
198 +</Tabs>
199 +
200 +### authorize()
201 +
202 +Manually authenticate a user to a toolkit outside of the chat flow.
203 +
204 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
205 +<Tab value="Python">
206 +```python
207 +connection_request = session.authorize("github")
208 +
209 +print(connection_request.redirect_url)
210 +
211 +connected_account = connection_request.wait_for_connection()
212 +```
213 +</Tab>
214 +<Tab value="TypeScript">
215 +```typescript
216 +const connectionRequest = await session.authorize("github", {
217 + callbackUrl: "https://myapp.com/callback",
218 +});
219 +
220 +console.log(connectionRequest.redirectUrl);
221 +
222 +const connectedAccount = await connectionRequest.waitForConnection();
223 +```
224 +</Tab>
225 +</Tabs>
226 +
227 +For more details, see [Manually authenticating users](/tool-router/manually-authenticating-users).
228 +
229 +### toolkits()
230 +
231 +List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
232 +
233 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
234 +<Tab value="Python">
235 +```python
236 +toolkits = session.toolkits()
237 +
238 +for toolkit in toolkits.items:
239 + status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
240 + print(f"{toolkit.name}: {status}")
241 +```
242 +</Tab>
243 +<Tab value="TypeScript">
244 +```typescript
245 +const toolkits = await session.toolkits();
246 +
247 +toolkits.items.forEach((toolkit) => {
248 + console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount?.id ?? "Not connected"}`);
249 +});
250 +```
251 +</Tab>
252 +</Tabs>
253 +
254 +Returns the first 20 toolkits by default.
fumadocs/content/tool-router/using-as-a-native-tool.mdx new
+240
@@ -0,0 +1,240 @@
1 +---
2 +title: Using as a native tool
3 +description: Use Tool Router as a native tool with any AI framework
4 +---
5 +
6 +Tool Router can be used as a single native tool with any AI framework. The tool handles search, authentication, and execution internally.
7 +
8 +## Examples for popular frameworks
9 +
10 +Jump to examples for:
11 +- [OpenAI](#openai) - Python, TypeScript
12 +- [Vercel AI SDK](#vercel-ai-sdk) - TypeScript
13 +
14 +## OpenAI
15 +
16 +### Installation
17 +
18 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 +<Tab value="Python">
20 +```bash
21 +pip install python-dotenv composio composio-openai-agents openai-agents
22 +```
23 +</Tab>
24 +<Tab value="TypeScript">
25 +```bash
26 +npm install @composio/core @composio/openai-agents @openai/agents
27 +```
28 +</Tab>
29 +</Tabs>
30 +
31 +### Usage
32 +
33 +Create a Tool Router session and use it as a native tool with OpenAI Agents SDK:
34 +
35 +<Callout type="info">
36 +- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
37 +- Set your `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
38 +</Callout>
39 +
40 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
41 +<Tab value="Python">
42 +```python
43 +from dotenv import load_dotenv
44 +from composio import Composio
45 +from agents import Agent, Runner, SQLiteSession
46 +from composio_openai_agents import OpenAIAgentsProvider
47 +
48 +load_dotenv()
49 +
50 +# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
51 +composio = Composio(provider=OpenAIAgentsProvider())
52 +
53 +# Unique identifier of the user
54 +user_id = "user_123"
55 +
56 +# Create a session and get native tools for the user
57 +session = composio.create(user_id=user_id)
58 +tools = session.tools()
59 +
60 +# Configure OpenAI agent with Composio tools
61 +agent = Agent(
62 + name="Personal Assistant",
63 + instructions="You are a helpful personal assistant. Use Composio tools to take action.",
64 + model="gpt-5.2",
65 + tools=tools,
66 +)
67 +
68 +# Memory for multi-turn conversation
69 +memory = SQLiteSession("conversation")
70 +
71 +# Execute an initial task
72 +print("Fetching GitHub issues from the Composio repository...\n")
73 +try:
74 + result = Runner.run_sync(
75 + starting_agent=agent,
76 + input="Fetch all the open GitHub issues on the @ComposioHQ/composio repository and group them by bugs/features/docs.",
77 + session=memory,
78 + )
79 + print(f"{result.final_output}\n")
80 +except Exception as e:
81 + print(f"[Error]: {e}")
82 +
83 +# Continue with interactive conversation
84 +print("\nWhat else would you like me to do? (Type 'exit' to exit)")
85 +
86 +while True:
87 + user_input = input("You: ").strip()
88 + if user_input.lower() == "exit":
89 + break
90 +
91 + print("Assistant: ", end="", flush=True)
92 + try:
93 + result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
94 + print(f"{result.final_output}\n")
95 + except Exception as e:
96 + print(f"\n[Error]: {e}")
97 +```
98 +</Tab>
99 +<Tab value="TypeScript">
100 +```typescript
101 +import "dotenv/config";
102 +import { Composio } from "@composio/core";
103 +import { Agent, run, MemorySession } from "@openai/agents";
104 +import { OpenAIAgentsProvider } from "@composio/openai-agents";
105 +import { createInterface } from "readline/promises";
106 +
107 +// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
108 +const composio = new Composio({ provider: new OpenAIAgentsProvider() });
109 +
110 +// Unique identifier of the user
111 +const userId = "user_123";
112 +
113 +// Create a session and get native tools for the user
114 +const session = await composio.create(userId);
115 +const tools = await session.tools();
116 +
117 +const agent = new Agent({
118 + name: "Personal Assistant",
119 + instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
120 + model: "gpt-5.2",
121 + tools,
122 +});
123 +
124 +// Create a memory session for persistent multi-turn conversation
125 +const memory = new MemorySession();
126 +
127 +// Execute an initial task
128 +console.log("Fetching GitHub issues from the Composio repository...\n");
129 +try {
130 + const initialResult = await run(
131 + agent,
132 + "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
133 + { session: memory }
134 + );
135 + console.log(`${initialResult.finalOutput}\n`);
136 +} catch (error) {
137 + console.error("[Error]:", error instanceof Error ? error.message : error);
138 +}
139 +
140 +// Continue with interactive conversation
141 +const readline = createInterface({ input: process.stdin, output: process.stdout });
142 +
143 +console.log(`
144 +What else would you like me to do?
145 +(Type 'exit' to exit)
146 +`);
147 +
148 +
149 +while (true) {
150 + const input = (await readline.question("You: ")).trim();
151 + if (input.toLowerCase() === "exit") break;
152 +
153 + console.log("Assistant: ");
154 +
155 + try {
156 + const result = await run(agent, input, { session: memory });
157 + console.log(`${result.finalOutput}\n`);
158 + } catch (error) {
159 + console.error("\n[Error]:", error instanceof Error ? error.message : error);
160 + }
161 +}
162 +readline.close();
163 +```
164 +</Tab>
165 +</Tabs>
166 +
167 +## Vercel AI SDK
168 +
169 +### Installation
170 +
171 +```bash
172 +npm install @composio/core @composio/vercel ai @ai-sdk/anthropic
173 +```
174 +
175 +### Usage
176 +
177 +Create a Tool Router session and use it as a native tool with Vercel AI SDK:
178 +
179 +<Callout type="info">
180 +- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
181 +- Set your `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://console.anthropic.com/settings/keys).
182 +</Callout>
183 +
184 +```typescript
185 +import "dotenv/config";
186 +import { anthropic } from "@ai-sdk/anthropic";
187 +import { Composio } from "@composio/core";
188 +import { VercelProvider } from "@composio/vercel";
189 +import { stepCountIs, streamText } from "ai";
190 +
191 +// Initialize Composio with Vercel provider (API key from env var COMPOSIO_API_KEY)
192 +const composio = new Composio({ provider: new VercelProvider() });
193 +
194 +// Unique identifier of the user
195 +const userId = "user_123";
196 +
197 +// Create a session and get native tools for the user
198 +const session = await composio.create(userId);
199 +const tools = await session.tools();
200 +
201 +console.log("Fetching GitHub issues from the Composio repository...");
202 +
203 +// Stream the response with tool calling
204 +const stream = await streamText({
205 + system: "You are a helpful personal assistant. Use Composio tools to take action.",
206 + model: anthropic("claude-sonnet-4-5"),
207 + prompt: "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
208 + stopWhen: stepCountIs(10),
209 + onStepFinish: (step) => {
210 + for (const toolCall of step.toolCalls) {
211 + console.log(`[Using tool: ${toolCall.toolName}]`);
212 + }
213 + },
214 + tools,
215 +});
216 +
217 +for await (const textPart of stream.textStream) {
218 + process.stdout.write(textPart);
219 +}
220 +
221 +console.log("\n\n---");
222 +console.log("Tip: If prompted to authenticate, complete the auth flow and run again.");
223 +```
224 +
225 +## Next steps
226 +
227 +<Cards>
228 + <Card title="Quickstart" href="/tool-router/quickstart">
229 + See both MCP and native tool in action
230 + </Card>
231 + <Card title="Using with MCP" href="/tool-router/using-with-mcp-clients">
232 + Use Tool Router with MCP-compatible clients
233 + </Card>
234 + <Card title="Authentication" href="/tool-router/authentication">
235 + Learn about authentication options
236 + </Card>
237 + <Card title="Session management" href="/tool-router/users-and-sessions">
238 + Configure sessions for your users
239 + </Card>
240 +</Cards>
fumadocs/content/tool-router/using-custom-auth-configs.mdx new
+61
@@ -0,0 +1,61 @@
1 +---
2 +title: Using custom auth configs
3 +description: Set up auth configs for toolkits without Composio managed authentication
4 +---
5 +
6 +Some toolkits don't have Composio managed authentication and require you to provide your own credentials. When Tool Router tries to use these toolkits, it will throw an error asking you to create an auth config.
7 +
8 +<Steps>
9 +<Step>
10 +### Check if a toolkit needs custom credentials
11 +
12 +In the [Composio platform](https://platform.composio.dev), go to "All Toolkits" and select the toolkit. If it shows no Composio managed auth schemes, you'll need to create an auth config.
13 +</Step>
14 +
15 +<Step>
16 +### Create an auth config
17 +
18 +1. Go to **Authentication management** in the [dashboard](https://app.composio.dev)
19 +2. Click **Create Auth Config**
20 +3. Select the toolkit
21 +4. Choose the auth scheme (OAuth2, API Key, etc.)
22 +5. Enter your credentials (client ID, client secret, API key, etc.)
23 +6. Click **Create**
24 +
25 +Copy the auth config ID (e.g., `ac_1234abcd`).
26 +
27 +<Callout type="info">
28 +For detailed instructions on getting credentials for specific toolkits, see [Custom auth configs](/docs/custom-auth-configs).
29 +</Callout>
30 +</Step>
31 +
32 +<Step>
33 +### Use in Tool Router
34 +
35 +Pass your auth config ID when creating a session:
36 +
37 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
38 +<Tab value="Python">
39 +```python
40 +session = composio.create(
41 + user_id="user_123",
42 + auth_configs={
43 + "posthog": "ac_your_posthog_config"
44 + }
45 +)
46 +```
47 +</Tab>
48 +<Tab value="TypeScript">
49 +```typescript
50 +const session = await composio.create("user_123", {
51 + authConfigs: {
52 + posthog: "ac_your_posthog_config",
53 + },
54 +});
55 +```
56 +</Tab>
57 +</Tabs>
58 +
59 +Tool Router will now use your auth config when users connect to this toolkit.
60 +</Step>
61 +</Steps>
fumadocs/content/tool-router/using-in-chat-authentication.mdx new
+179
@@ -0,0 +1,179 @@
1 +---
2 +title: Using In-chat authentication
3 +description: Let your agent prompt users to connect accounts during conversation
4 +---
5 +
6 +In-chat authentication lets your agent prompt users to connect accounts during chat. When a tool requires authentication, the agent returns a Connect Link URL. The user authenticates, confirms in chat, and the agent retries.
7 +
8 +## How it works
9 +
10 +1. Agent searches for tools via the `COMPOSIO_SEARCH_TOOLS` meta-tool
11 +2. The `COMPOSIO_MANAGE_CONNECTIONS` meta-tool checks connection status, returns Connect Link URL if needed
12 +3. User authenticates, confirms in chat, agent continues
13 +
14 +## Configuration
15 +
16 +By just creating a session with default configs, you are enabling in-chat auth. The `manage_connections` parameter defaults to `True`, which includes the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool automatically:
17 +
18 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 +<Tab value="Python">
20 +```python
21 +session = composio.create(user_id="user_123")
22 +```
23 +</Tab>
24 +<Tab value="TypeScript">
25 +```typescript
26 +const session = await composio.create("user_123");
27 +```
28 +</Tab>
29 +</Tabs>
30 +
31 +### Custom callback URL
32 +
33 +Redirect users back to your chat page after they complete authentication:
34 +
35 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
36 +<Tab value="Python">
37 +```python
38 +session = composio.create(
39 + user_id="user_123",
40 + manage_connections={
41 + "callback_url": "https://yourapp.com/chat"
42 + },
43 +)
44 +```
45 +</Tab>
46 +<Tab value="TypeScript">
47 +```typescript
48 +const session = await composio.create("user_123", {
49 + manageConnections: {
50 + callbackUri: "https://yourapp.com/chat",
51 + },
52 +});
53 +```
54 +</Tab>
55 +</Tabs>
56 +
57 +## Examples
58 +
59 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
60 +<Tab value="Python">
61 +```python
62 +from dotenv import load_dotenv
63 +from composio import Composio
64 +from agents import Agent, Runner, SQLiteSession
65 +from composio_openai_agents import OpenAIAgentsProvider
66 +
67 +load_dotenv()
68 +
69 +# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
70 +composio = Composio(provider=OpenAIAgentsProvider())
71 +
72 +# Unique identifier of the user
73 +user_id = "user_123"
74 +
75 +# Create a session and get native tools for the user
76 +session = composio.create(user_id=user_id)
77 +tools = session.tools()
78 +
79 +# Configure OpenAI agent with Composio tools
80 +agent = Agent(
81 + name="Personal Assistant",
82 + instructions="You are a helpful personal assistant. Use Composio tools to take action.",
83 + model="gpt-5.2",
84 + tools=tools,
85 +)
86 +
87 +# Memory for multi-turn conversation
88 +memory = SQLiteSession("conversation")
89 +
90 +print("""
91 +What task would you like me to help you with?
92 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
93 +(Type 'exit' to exit)
94 +Example tasks:
95 + • 'Summarize my emails from today'
96 + • 'List all open issues on the composio github repository'
97 +""")
98 +
99 +while True:
100 + user_input = input("You: ").strip()
101 + if user_input.lower() == "exit":
102 + break
103 +
104 + print("Assistant: ", end="", flush=True)
105 + try:
106 + result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
107 + print(f"{result.final_output}\n")
108 + except Exception as e:
109 + print(f"\n[Error]: {e}")
110 +```
111 +</Tab>
112 +<Tab value="TypeScript">
113 +```typescript
114 +import "dotenv/config";
115 +import { Composio } from "@composio/core";
116 +import { Agent, run, MemorySession } from "@openai/agents";
117 +import { OpenAIAgentsProvider } from "@composio/openai-agents";
118 +import { createInterface } from "readline/promises";
119 +
120 +// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)
121 +const composio = new Composio({ provider: new OpenAIAgentsProvider() });
122 +
123 +// Unique identifier of the user
124 +const userId = "user_123";
125 +// Create a tool router session for the user
126 +const session = await composio.create(userId);
127 +const tools = await session.tools();
128 +
129 +const agent = new Agent({
130 + name: "Personal Assistant",
131 + instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
132 + model: "gpt-5.2",
133 + tools,
134 +});
135 +
136 +// Set up interactive terminal input/output for the conversation
137 +const readline = createInterface({ input: process.stdin, output: process.stdout });
138 +// Create a memory session for persistent multi-turn conversation
139 +const memory = new MemorySession();
140 +
141 +console.log(`
142 +What task would you like me to help you with?
143 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
144 +(Type 'exit' to exit)
145 +Example tasks:
146 + • 'Summarize my emails from today'
147 + • 'List all open issues on the composio github repository and create a Google Sheet with the issues'
148 +`);
149 +
150 +// Multi-turn conversation with agentic tool calling
151 +while (true) {
152 + const query = await readline.question("You: ");
153 + const input = query.trim();
154 +
155 + if (input.toLowerCase() === "exit") break;
156 + process.stdout.write("Assistant: ");
157 +
158 + try {
159 + const result = await run(agent, input, { session: memory });
160 + process.stdout.write(`${result.finalOutput}`);
161 + } catch (error) {
162 + console.error("\n[Error]:", error instanceof Error ? error.message : error);
163 + }
164 +}
165 +readline.close();
166 +```
167 +</Tab>
168 +</Tabs>
169 +
170 +What this looks like when you run the code:
171 +
172 +```
173 +Assistant: What would you like me to do today? Type 'exit' to end the conversation.
174 +
175 +> Star the composio repo on GitHub
176 +Assistant: I need you to connect your GitHub account first.
177 +Please click here to authorize: https://connect.composio.dev/link/ln_abc123
178 +
179 +> Done
\ No newline at end of file
fumadocs/content/tool-router/using-with-mcp-clients.mdx new
+405
@@ -0,0 +1,405 @@
1 +---
2 +title: Using with MCP clients
3 +description: Use Tool Router as an MCP server with any MCP client
4 +---
5 +
6 +Every Tool Router session provides a unique MCP server URL. This URL exposes the exact session you created - with the specific user, toolkits, and auth configs you configured. Any MCP client that supports HTTP transport can connect using just the URL and your API key.
7 +
8 +## Examples for popular frameworks
9 +
10 +Jump to examples for:
11 +- [Claude Agent SDK](#claude-agent-sdk) - Python, TypeScript
12 +- [OpenAI Agents SDK](#openai-agents-sdk) - Python, TypeScript
13 +- [Vercel AI SDK](#vercel-ai-sdk) - TypeScript
14 +
15 +## Claude Agent SDK
16 +
17 +### Installation
18 +
19 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
20 +<Tab value="Python">
21 +```bash
22 +pip install python-dotenv composio claude-agent-sdk
23 +```
24 +</Tab>
25 +<Tab value="TypeScript">
26 +```bash
27 +npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk
28 +```
29 +</Tab>
30 +</Tabs>
31 +
32 +### Usage
33 +
34 +Create a Tool Router session and execute tasks with Claude:
35 +
36 +<Callout type="info">
37 +- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
38 +- Set your `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).
39 +</Callout>
40 +
41 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
42 +<Tab value="Python">
43 +```python
44 +import asyncio
45 +from dotenv import load_dotenv
46 +from claude_agent_sdk.client import ClaudeSDKClient
47 +from claude_agent_sdk.types import (
48 + ClaudeAgentOptions,
49 + AssistantMessage,
50 + TextBlock,
51 + ToolUseBlock,
52 +)
53 +from composio import Composio
54 +
55 +load_dotenv()
56 +
57 +# Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly)
58 +composio = Composio()
59 +
60 +# Unique identifier of the user
61 +user_id = "user_123"
62 +# Create a tool router session for the user
63 +session = composio.create(user_id=user_id)
64 +
65 +# Configure Claude with Composio MCP server
66 +options = ClaudeAgentOptions(
67 + system_prompt=(
68 + "You are a helpful assistant with access to external tools. "
69 + "Always use the available tools to complete user requests."
70 + ),
71 + mcp_servers={
72 + "composio": {
73 + "type": "http",
74 + "url": session.mcp.url,
75 + "headers": session.mcp.headers, # Authentication headers for the Composio MCP server
76 + }
77 + },
78 + permission_mode="bypassPermissions", # Auto-approve tools (demo only)
79 +)
80 +
81 +async def main():
82 + print("""
83 +What task would you like me to help you with?
84 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
85 +(Type 'exit' to exit)
86 +Example tasks:
87 + • 'Summarize my emails from today'
88 + • 'List all open issues on the composio github repository and create a notion page with the issues'
89 +""")
90 +
91 + async with ClaudeSDKClient(options) as client:
92 + # Multi-turn conversation with agentic tool calling
93 + while True:
94 + user_input = input("\nYou: ").strip()
95 + if user_input.lower() == "exit":
96 + break
97 +
98 + print("\nClaude: ", end="", flush=True)
99 + try:
100 + await client.query(user_input)
101 + async for msg in client.receive_response():
102 + if isinstance(msg, AssistantMessage):
103 + for block in msg.content:
104 + if isinstance(block, ToolUseBlock):
105 + print(f"\n[Using tool: {block.name}]", end="")
106 + elif isinstance(block, TextBlock):
107 + print(block.text, end="", flush=True)
108 + except Exception as e:
109 + print(f"\n[Error]: {e}")
110 +
111 +if __name__ == "__main__":
112 + asyncio.run(main())
113 +```
114 +</Tab>
115 +<Tab value="TypeScript">
116 +```typescript
117 +import "dotenv/config";
118 +import { query, type Options } from "@anthropic-ai/claude-agent-sdk";
119 +import { Composio } from "@composio/core";
120 +import { createInterface } from "readline/promises";
121 +
122 +// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
123 +const composio = new Composio();
124 +
125 +// Unique identifier of the user
126 +const userId = "user_123";
127 +
128 +// Create a tool router session for the user
129 +const session = await composio.create(userId);
130 +
131 +const options: Options = {
132 + systemPrompt: `You are a helpful assistant with access to external tools. ` +
133 + `Always use the available tools to complete user requests.`,
134 + mcpServers: {
135 + composio: {
136 + type: "http",
137 + url: session.mcp.url,
138 + headers: session.mcp.headers // Authentication headers for the Composio MCP server
139 + },
140 + },
141 + permissionMode: "bypassPermissions", // Auto-approve tools (demo only - use "default" in production)
142 +};
143 +
144 +// Set up interactive terminal input/output for the conversation
145 +const readline = createInterface({ input: process.stdin, output: process.stdout });
146 +
147 +console.log(`
148 +What task would you like me to help you with?
149 +I can use tools like Gmail, GitHub, Linear, Notion, and more.
150 +(Type 'exit' to exit)
151 +Example tasks:
152 + • 'Summarize my emails from today'
153 + • 'List all open issues on the composio github repository and create a notion page with the issues'
154 +`);
155 +
156 +let isFirstQuery = true;
157 +
158 +// Multi-turn conversation with agentic tool calling
159 +while (true) {
160 + const answer = await readline.question('You: ');
161 + const input = answer.trim();
162 + if (input.toLowerCase() === "exit") break;
163 +
164 + process.stdout.write("Claude: ");
165 +
166 + const queryOptions = isFirstQuery ? options : { ...options, continue: true };
167 + isFirstQuery = false;
168 +
169 + try {
170 + for await (const stream of query({ prompt: input, options: queryOptions })) {
171 + // Only process assistant messages (the SDK also sends result/error messages)
172 + if (stream.type === "assistant") {
173 + const { content } = stream.message;
174 + for (const block of content) {
175 + if (block.type === "tool_use") {
176 + process.stdout.write(`\n[Using tool: ${block.name}]`);
177 + } else if (block.type === "text") {
178 + process.stdout.write(block.text);
179 + }
180 + }
181 + }
182 + }
183 + } catch (error) {
184 + console.error("\n[Error]:", error instanceof Error ? error.message : error);
185 + }
186 + process.stdout.write("\n");
187 +}
188 +
189 +readline.close();
190 +```
191 +</Tab>
192 +</Tabs>
193 +
194 +## OpenAI Agents SDK
195 +
196 +### Installation
197 +
198 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
199 +<Tab value="Python">
200 +```bash
201 +pip install python-dotenv composio openai-agents
202 +```
203 +</Tab>
204 +<Tab value="TypeScript">
205 +```bash
206 +npm install dotenv @composio/core @openai/agents zod@3
207 +```
208 +</Tab>
209 +</Tabs>
210 +
211 +### Usage
212 +
213 +Create a Tool Router session and execute tasks with OpenAI agents:
214 +
215 +<Callout type="info">
216 +- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
217 +- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).
218 +</Callout>
219 +
220 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
221 +<Tab value="Python">
222 +```python
223 +from dotenv import load_dotenv
224 +from composio import Composio
225 +from agents import Agent, Runner, HostedMCPTool
226 +
227 +load_dotenv()
228 +
229 +# Initialize Composio (API key from env var COMPOSIO_API_KEY)
230 +composio = Composio()
231 +# Unique identifier of the user
232 +user_id = "user_123"
233 +
234 +# Create a Tool Router session for the user
235 +session = composio.create(user_id=user_id)
236 +
237 +# Configure OpenAI agent with Composio MCP server
238 +agent = Agent(
239 + name="Personal Assistant",
240 + instructions="You are a helpful personal assistant. Use Composio tools to take action.",
241 + model="gpt-5.2",
242 + tools=[
243 + HostedMCPTool(
244 + tool_config={
245 + "type": "mcp",
246 + "server_label": "composio",
247 + "server_url": session.mcp.url,
248 + "require_approval": "never",
249 + "headers": session.mcp.headers,
250 + }
251 + )
252 + ],
253 +)
254 +
255 +# Execute the task
256 +print("Fetching GitHub issues from the Composio repository @ComposioHQ/composio...\n")
257 +try:
258 + result = Runner.run_sync(
259 + starting_agent=agent,
260 + input="Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
261 + )
262 + print(result.final_output)
263 +except Exception as e:
264 + print(f"[Error]: {e}")
265 +
266 +print("\n\n---")
267 +print("Tip: If prompted to authenticate, complete the auth flow and run again.")
268 +```
269 +</Tab>
270 +<Tab value="TypeScript">
271 +```typescript
272 +import "dotenv/config";
273 +import { Composio } from "@composio/core";
274 +import { Agent, hostedMcpTool, run, MemorySession } from "@openai/agents";
275 +import { createInterface } from "readline/promises";
276 +
277 +// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
278 +const composio = new Composio();
279 +
280 +// Unique identifier of the user
281 +const userId = "user_123";
282 +
283 +// Create a tool router session for the user
284 +const session = await composio.create(userId);
285 +
286 +const agent = new Agent({
287 + name: "Personal Assistant",
288 + instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
289 + model: "gpt-5.2",
290 + tools: [
291 + hostedMcpTool({
292 + serverLabel: "composio",
293 + serverUrl: session.mcp.url,
294 + headers: session.mcp.headers, // Authentication headers for the Composio MCP server
295 + }),
296 + ],
297 +});
298 +
299 +// Create a memory session for persistent multi-turn conversation
300 +const memory = new MemorySession();
301 +
302 +// Execute an initial task
303 +console.log("Fetching GitHub issues from the Composio repository...\n");
304 +try {
305 + const initialResult = await run(
306 + agent,
307 + "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",
308 + { session: memory }
309 + );
310 + console.log(`${initialResult.finalOutput}\n`);
311 +} catch (error) {
312 + console.error("[Error]:", error instanceof Error ? error.message : error);
313 +}
314 +
315 +// Continue with interactive conversation
316 +const readline = createInterface({ input: process.stdin, output: process.stdout });
317 +
318 +console.log(`
319 +What else would you like me to do?
320 +(Type 'exit' to exit)
321 +`);
322 +
323 +while (true) {
324 + const input = (await readline.question("You: ")).trim();
325 + if (input.toLowerCase() === "exit") break;
326 +
327 + console.log("Assistant: ");
328 +
329 + try {
330 + const result = await run(agent, input, { session: memory });
331 + console.log(`${result.finalOutput}\n`);
332 + } catch (error) {
333 + console.error("\n[Error]:", error instanceof Error ? error.message : error);
334 + }
335 +}
336 +readline.close();
337 +```
338 +</Tab>
339 +</Tabs>
340 +
341 +## Vercel AI SDK
342 +
343 +### Installation
344 +
345 +```bash
346 +npm install dotenv @composio/core ai @ai-sdk/anthropic @ai-sdk/mcp
347 +```
348 +
349 +### Usage
350 +
351 +Use Tool Router with Vercel AI SDK's `generateText` for single completions:
352 +
353 +<Callout type="info">
354 +- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).
355 +- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).
356 +</Callout>
357 +
358 +```typescript
359 +import "dotenv/config";
360 +import { anthropic } from "@ai-sdk/anthropic";
361 +import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";
362 +import { Composio } from "@composio/core";
363 +import { stepCountIs, streamText } from "ai";
364 +
365 +// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })
366 +const composio = new Composio();
367 +
368 +// Unique identifier of the user
369 +const userId = "user_123";
370 +
371 +// Create a tool router session for the user
372 +const { mcp } = await composio.create(userId);
373 +
374 +// Create an MCP client to connect to the Composio tool router
375 +const client = await createMCPClient({
376 + transport: {
377 + type: "http",
378 + url: mcp.url,
379 + headers: mcp.headers, // Authentication headers for the Composio MCP server
380 + },
381 +});
382 +const tools = await client.tools();
383 +
384 +console.log("Summarizing your emails from today");
385 +
386 +const stream = await streamText({
387 + system: "You are a helpful personal assistant. Use Composio tools to take action.",
388 + model: anthropic("claude-sonnet-4-5"),
389 + prompt: "Summarize my emails from today",
390 + stopWhen: stepCountIs(10),
391 + onStepFinish: (step) => {
392 + for (const toolCall of step.toolCalls) {
393 + console.log(`[Using tool: ${toolCall.toolName}]`);
394 + }
395 + },
396 + tools,
397 +});
398 +
399 +for await (const textPart of stream.textStream) {
400 + process.stdout.write(textPart);
401 +}
402 +
403 +console.log("\n\n---");
404 +console.log("Tip: If prompted to authenticate, complete the auth flow and run again.")
405 +```
fumadocs/content/tool-router/white-labeling-authentication.mdx new
+150
@@ -0,0 +1,150 @@
1 +---
2 +title: White-labeling authentication
3 +description: Use your own OAuth apps and branded auth screens
4 +---
5 +
6 +White-labeling lets you use your own OAuth apps instead of Composio's. Users will see your app name on consent screens instead of "Composio".
7 +
8 +By default, OAuth screens show Composio's branding. With white-labeling, they'll see your app name and logo.
9 +
10 +<Steps>
11 +<Step>
12 +### Create an OAuth app
13 +
14 +Create a developer app in the toolkit's developer portal. You'll need the client ID and client secret. Set the callback URL to:
15 +
16 +```
17 +https://backend.composio.dev/api/v3/toolkits/auth/callback
18 +```
19 +
20 +<Callout type="info">
21 +For step-by-step guides on creating OAuth apps for some toolkits, see [composio.dev/auth](https://composio.dev/auth).
22 +</Callout>
23 +</Step>
24 +
25 +<Step>
26 +### Create auth config
27 +
28 +Create an auth config in the [Composio dashboard](https://app.composio.dev):
29 +
30 +1. Go to **Authentication management** → **Create Auth Config**
31 +2. Select the toolkit (e.g., GitHub)
32 +3. Choose **OAuth2** scheme
33 +4. Enter your **Client ID** and **Client Secret**
34 +5. Select the scopes you need
35 +6. Click **Create**
36 +
37 +Copy the auth config ID (e.g., `ac_1234abcd`).
38 +
39 +<Callout type="info">
40 +For detailed instructions with screenshots, see [Custom auth configs](/docs/custom-auth-configs).
41 +</Callout>
42 +</Step>
43 +
44 +<Step>
45 +### Use in Tool Router
46 +
47 +Pass your auth config ID in the session:
48 +
49 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
50 +<Tab value="Python">
51 +```python
52 +session = composio.create(
53 + user_id="user_123",
54 + auth_configs={
55 + "github": "ac_your_github_config"
56 + },
57 +)
58 +```
59 +</Tab>
60 +<Tab value="TypeScript">
61 +```typescript
62 +const session = await composio.create("user_123", {
63 + authConfigs: {
64 + github: "ac_your_github_config",
65 + },
66 +});
67 +```
68 +</Tab>
69 +</Tabs>
70 +
71 +When users connect GitHub, they'll see your OAuth app's name and logo on the consent screen.
72 +</Step>
73 +</Steps>
74 +
75 +## Mixing custom and Composio-managed auth
76 +
77 +You can white-label some toolkits while using Composio's managed credentials for others:
78 +
79 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
80 +<Tab value="Python">
81 +```python
82 +session = composio.create(
83 + user_id="user_123",
84 + auth_configs={
85 + "github": "ac_your_github_config",
86 + "slack": "ac_your_slack_config",
87 + # gmail, linear, etc. use Composio managed auth
88 + },
89 +)
90 +```
91 +</Tab>
92 +<Tab value="TypeScript">
93 +```typescript
94 +const session = await composio.create("user_123", {
95 + authConfigs: {
96 + github: "ac_your_github_config",
97 + slack: "ac_your_slack_config",
98 + // gmail, linear, etc. use Composio managed auth
99 + },
100 +});
101 +```
102 +</Tab>
103 +</Tabs>
104 +
105 +## Custom redirect domain
106 +
107 +When users authenticate, they briefly see `backend.composio.dev` in their browser URL. Composio needs to receive the OAuth callback to capture and store the authentication tokens.
108 +
109 +If you need to hide this URL (for enterprise compliance or complete white-labeling), you can proxy the redirect through your own domain:
110 +
111 +1. Set your OAuth app's redirect URI to your domain:
112 +```
113 +https://yourdomain.com/api/composio-redirect
114 +```
115 +
116 +2. Create an endpoint that forwards the OAuth callback to Composio:
117 +
118 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
119 +<Tab value="Python">
120 +```python
121 +from fastapi import FastAPI, Request
122 +from fastapi.responses import RedirectResponse
123 +
124 +app = FastAPI()
125 +
126 +@app.get("/api/composio-redirect")
127 +def composio_redirect(request: Request):
128 + # Forward all OAuth parameters to Composio
129 + composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"
130 + return RedirectResponse(url=f"{composio_url}?{request.url.query}")
131 +```
132 +</Tab>
133 +<Tab value="TypeScript">
134 +```typescript
135 +// pages/api/composio-redirect.ts (Next.js)
136 +import type { NextApiRequest, NextApiResponse } from "next";
137 +
138 +export default function handler(req: NextApiRequest, res: NextApiResponse) {
139 + // Forward all OAuth parameters to Composio
140 + const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";
141 + const params = new URLSearchParams(req.query as Record<string, string>);
142 + res.redirect(302, `${composioUrl}?${params.toString()}`);
143 +}
144 +```
145 +</Tab>
146 +</Tabs>
147 +
148 +3. Update your auth config in the Composio dashboard to use your custom redirect URI.
149 +
150 +This makes the OAuth flow go through your domain first, then to Composio for token storage.
fumadocs/lib/layout.shared.tsx
+1
@@ -42,6 +42,7 @@ export function baseOptions(): BaseLayoutProps {
42 {
43 text: 'Tool Router',
44 url: '/tool-router',
45 + active: 'nested-url',
46 },
47 {
48 text: 'Toolkits',
fumadocs/next.config.mjs
+9 -4
@@ -9,13 +9,18 @@ const config = {
9 return [
10 {
11 source: '/',
12 - destination: '/docs/welcome',
12 + destination: '/docs',
13 permanent: false,
14 },
15 {
16 - source: '/docs',
17 - destination: '/docs/welcome',
18 - permanent: false,
16 + source: '/docs/welcome',
17 + destination: '/docs',
18 + permanent: true,
19 + },
20 + {
21 + source: '/tool-router/overview',
22 + destination: '/tool-router',
23 + permanent: true,
24 },
25 ];
26 },