Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Add Tool Router documentation and restructure docs layout
Sushmithamallesh503bae8b1173
diff --git a/fumadocs/content/docs/welcome.mdx b/fumadocs/content/docs/index.mdxsimilarity index 100%rename from fumadocs/content/docs/welcome.mdxrename to fumadocs/content/docs/index.mdxdiff --git a/fumadocs/content/docs/meta.json b/fumadocs/content/docs/meta.jsonindex 77df35f94..b639b2f1f 100644--- a/fumadocs/content/docs/meta.json+++ b/fumadocs/content/docs/meta.json@@ -1,7 +1,7 @@{"pages": ["---Get Started---",- "welcome",+ "index","quickstart","capabilities","---Tools and Triggers---",diff --git a/fumadocs/content/tool-router/authentication.mdx b/fumadocs/content/tool-router/authentication.mdxnew file mode 100644index 000000000..8b37706ce--- /dev/null+++ b/fumadocs/content/tool-router/authentication.mdx@@ -0,0 +1,70 @@+---+title: Authentication+description: Understand how Tool Router handles user authentication to toolkits+---++Tool Router handles authentication through [Connect Links](/docs/authenticating-tools#hosted-authentication-connect-link), hosted pages where users complete OAuth or enter credentials.++## In-chat authentication++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.++Here's what this looks like in a conversation:++```+You: Star the composio repo on GitHub++Agent: I need you to connect your GitHub account first.+ Please click here to authorize: https://connect.composio.dev/link/ln_abc123++You: Done++Agent: Done! I've starred ComposioHQ/composio.+```++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).++## Manual authentication++For apps that manage auth outside of chat, use `session.authorize()` to generate Connect Links programmatically:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+connection_request = session.authorize("github")+print(connection_request.redirect_url)+# https://connect.composio.dev/link/ln_abc123+```+</Tab>+<Tab value="TypeScript">+```typescript+const connectionRequest = await session.authorize("github");+console.log(connectionRequest.redirectUrl);+// https://connect.composio.dev/link/ln_abc123+```+</Tab>+</Tabs>++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.++## How Tool Router manages auth configs++When executing a tool, Tool Router needs an auth config to find or create a connected account. It handles this automatically:++1. Uses your `authConfigs` override if provided+2. Otherwise, reuses an auth config it previously created for this toolkit+3. If none exists, creates one using Composio managed auth++You don't need to create auth configs manually for most toolkits.++## Supported auth methods++Tool Router supports **Composio managed OAuth** (GitHub, Gmail, Slack, and most toolkits) and **API key auth** (users enter their own keys via Connect Link).++<Callout type="info">+Toolkits without Composio managed auth require a custom auth config. See [Using custom auth configs](/tool-router/using-custom-auth-configs).+</Callout>++## White-labeling++Show your own branding on OAuth consent screens by creating your own OAuth app. See [White-labeling authentication](/tool-router/white-labeling-authentication).diff --git a/fumadocs/content/tool-router/managing-multiple-accounts.mdx b/fumadocs/content/tool-router/managing-multiple-accounts.mdxnew file mode 100644index 000000000..3155e949c--- /dev/null+++ b/fumadocs/content/tool-router/managing-multiple-accounts.mdx@@ -0,0 +1,133 @@+---+title: Managing multiple accounts+description: Handle users with multiple accounts for the same toolkit+---++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.++## Default account behavior++When multiple accounts are connected for the same toolkit:+- Each session can only use **one account per toolkit** at a time+- Tool Router uses the **most recently connected account** by default+- You can override this by explicitly selecting an account+- Each account maintains its own authentication and permissions++## Connecting multiple accounts++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).++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(user_id="user_123")++# Connect first account (work)+work_auth = session.authorize("gmail")+print(f"Connect work Gmail: {work_auth.redirect_url}")+work_connection = work_auth.wait_for_connection()+print(f"Work account connected: {work_connection.id}")++# Connect second account (personal)+personal_auth = session.authorize("gmail")+print(f"Connect personal Gmail: {personal_auth.redirect_url}")+personal_connection = personal_auth.wait_for_connection()+print(f"Personal account connected: {personal_connection.id}")+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123");++// Connect first account (work)+const workAuth = await session.authorize("gmail");+console.log(`Connect work Gmail: ${workAuth.redirectUrl}`);+const workConnection = await workAuth.waitForConnection();+console.log(`Work account connected: ${workConnection.id}`);++// Connect second account (personal)+const personalAuth = await session.authorize("gmail");+console.log(`Connect personal Gmail: ${personalAuth.redirectUrl}`);+const personalConnection = await personalAuth.waitForConnection();+console.log(`Personal account connected: ${personalConnection.id}`);+```+</Tab>+</Tabs>++<Callout type="info">+Store the account IDs returned after connection to explicitly select accounts later.+</Callout>++## Selecting a specific account for a session++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:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+# This session will use a specific Gmail account+session = composio.create(+ user_id="user_123",+ connected_accounts={+ "gmail": "ca_specific_account_id", # Connected account ID+ },+)++# To switch accounts, create a new session with a different account ID+session2 = composio.create(+ user_id="user_123",+ connected_accounts={+ "gmail": "ca_different_account_id", # Different account+ },+)+```+</Tab>+<Tab value="TypeScript">+```typescript+// This session will use a specific Gmail account+const session = await composio.create("user_123", {+ connectedAccounts: {+ gmail: "ca_specific_account_id", // Connected account ID+ },+});++// To switch accounts, create a new session with a different account ID+const session2 = await composio.create("user_123", {+ connectedAccounts: {+ gmail: "ca_different_account_id", // Different account+ },+});+```+</Tab>+</Tabs>++## Listing all user accounts++To list all accounts a user has connected (not just the active one), see [List accounts](/docs/connected-accounts#list-accounts).++## Viewing session's active account++Use `session.toolkits()` to see which account is currently active in the session:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+toolkits = session.toolkits()++for toolkit in toolkits.items:+ if toolkit.connection.connected_account:+ print(f"{toolkit.name}: {toolkit.connection.connected_account.id}")+```+</Tab>+<Tab value="TypeScript">+```typescript+const toolkits = await session.toolkits();++for (const toolkit of toolkits.items) {+ if (toolkit.connection.connectedAccount) {+ console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount.id}`);+ }+}+```+</Tab>+</Tabs>diff --git a/fumadocs/content/tool-router/manually-authenticating-users.mdx b/fumadocs/content/tool-router/manually-authenticating-users.mdxnew file mode 100644index 000000000..fb8a8db40--- /dev/null+++ b/fumadocs/content/tool-router/manually-authenticating-users.mdx@@ -0,0 +1,162 @@+---+title: Manually authenticating users+description: Authenticate users to toolkits outside of chat+---++Manual authentication lets you connect users to toolkits outside of the chat flow. Use this when you want to:+- Pre-authenticate users before they start chatting+- Build a custom connections UI in your app++## Authorize a toolkit++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:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(user_id="user_123")++connection_request = session.authorize("gmail")++print(connection_request.redirect_url)+# https://connect.composio.dev/link/ln_abc123++connected_account = connection_request.wait_for_connection(60000)+print(f"Connected: {connected_account.id}")+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123");++const connectionRequest = await session.authorize("gmail");++console.log(connectionRequest.redirectUrl);+// https://connect.composio.dev/link/ln_abc123++const connectedAccount = await connectionRequest.waitForConnection(60000);+console.log(`Connected: ${connectedAccount.id}`);+```+</Tab>+</Tabs>++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).++<Callout type="info">+If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.+</Callout>++## Check connection status++Use `session.toolkits()` to see all toolkits in the session and their connection status:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+toolkits = session.toolkits()++for toolkit in toolkits.items:+ status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"+ print(f"{toolkit.name}: {status}")+```+</Tab>+<Tab value="TypeScript">+```typescript+const toolkits = await session.toolkits();++toolkits.items.forEach((toolkit) => {+ console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount?.id ?? "Not connected"}`);+});+```+</Tab>+</Tabs>++## Disabling in-chat auth++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:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ manage_connections=False,+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ manageConnections: false,+});+```+</Tab>+</Tabs>++## Putting it together++A common pattern is to verify all required connections before starting the agent:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from composio import Composio++composio = Composio(api_key="your-api-key")++required_toolkits = ["gmail", "github"]++session = composio.create(+ user_id="user_123",+ manage_connections=False, # Disable in-chat auth prompts+)++toolkits = session.toolkits()++connected = {t.slug for t in toolkits.items if t.connection.is_active}+pending = [slug for slug in required_toolkits if slug not in connected]++print(f"Connected: {connected}")+print(f"Pending: {pending}")++for slug in pending:+ connection_request = session.authorize(slug)+ print(f"Connect {slug}: {connection_request.redirect_url}")+ connection_request.wait_for_connection()++print(f"All toolkits connected! MCP URL: {session.mcp.url}")+```+</Tab>+<Tab value="TypeScript">+```typescript+import { Composio } from "@composio/core";++const composio = new Composio({ apiKey: "your-api-key" });++const requiredToolkits = ["gmail", "github"];++const session = await composio.create("user_123", {+ manageConnections: false, // Disable in-chat auth prompts+});++const toolkits = await session.toolkits();++const connected = toolkits.items+ .filter((t) => t.connection.connectedAccount)+ .map((t) => t.slug);++const pending = requiredToolkits.filter((slug) => !connected.includes(slug));++console.log("Connected:", connected);+console.log("Pending:", pending);++for (const slug of pending) {+ const connectionRequest = await session.authorize(slug);+ console.log(`Connect ${slug}: ${connectionRequest.redirectUrl}`);+ await connectionRequest.waitForConnection();+}++console.log(`All toolkits connected! MCP URL: ${session.mcp.url}`);+```+</Tab>+</Tabs>diff --git a/fumadocs/content/tool-router/meta.json b/fumadocs/content/tool-router/meta.jsonindex bb8f15a9a..b1319eea9 100644--- a/fumadocs/content/tool-router/meta.json+++ b/fumadocs/content/tool-router/meta.json@@ -2,6 +2,21 @@"title": "Tool Router","pages": ["---Get Started---",- "index"+ "index",+ "quickstart",+ "---Core Concepts---",+ "users-and-sessions",+ "authentication",+ "tools-and-toolkits",+ "---Guides---",+ "using-in-chat-authentication",+ "manually-authenticating-users",+ "managing-multiple-accounts",+ "white-labeling-authentication",+ "using-custom-auth-configs",+ "using-with-mcp-clients",+ "using-as-a-native-tool",+ "---Resources---",+ "migration-guide"]}diff --git a/fumadocs/content/tool-router/migration-guide/beta-to-stable.mdx b/fumadocs/content/tool-router/migration-guide/beta-to-stable.mdxnew file mode 100644index 000000000..bcf9f13ab--- /dev/null+++ b/fumadocs/content/tool-router/migration-guide/beta-to-stable.mdx@@ -0,0 +1,108 @@+---+title: Beta to Stable Migration+description: Migrate from Tool Router beta to the stable version+---++The stable version includes improved session management, multiple configuring options, and enhanced authentication capabilities.++## The basics++<Steps>+<Step>+### Upgrade composio package++Upgrade to the latest stable version:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```bash+pip install --upgrade composio+```+</Tab>+<Tab value="TypeScript">+```bash+npm install @composio/core@latest+```+</Tab>+</Tabs>+</Step>++<Step>+### Update session creation++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+# Beta (before)+session = composio.experimental.tool_router.create_session(+ user_id="[email protected]"+)++# Stable (after)+session = composio.create(+ user_id="[email protected]"+)+```+</Tab>+<Tab value="TypeScript">+```typescript+// Beta (before)+const session = await composio.experimental.toolRouter.createSession('user_123');++// Stable (after)+const session = await composio.create('user_123');+```+</Tab>+</Tabs>+</Step>++<Step>+### Moving users (optional)++If you have existing users on tool router and you don't want them to authenticate again:+- Tool Router will auto-detect auth configs and connected accounts it created (from the beta version).+- If you have custom auth configs (not created by Tool Router):+ - Search for the Auth config for that connected account. See [Connected Accounts](/docs/connected-accounts) to fetch existing accounts programmatically.+ - While creating a session configure to use this Auth config.+ - You need to repeat this for each toolkit you want to enable for that session.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ auth_configs={+ "github": "ac_your_github_config",+ "slack": "ac_your_slack_config"+ }+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create('user_123',+ {+ authConfigs: {+ github: "ac_your_github_config",+ slack: "ac_your_slack_config",+ },+ }+);+```+</Tab>+</Tabs>+</Step>++<Step>+### Explore new capabilities++Check out these new features available in the stable version:++- **[Native tools](/tool-router/using-as-a-native-tool)**: Use Tool Router with any AI framework+- **Better [session](/tool-router/users-and-sessions) and [auth](/tool-router/authentication) config**+- **[Multi-account support](/tool-router/managing-multiple-accounts)**: Manage multiple accounts per user seamlessly+- **[Manual authentication](/tool-router/manually-authenticating-users)**: Control when and how users authenticate+- **[Custom auth](/tool-router/using-custom-auth-configs)**: Support for toolkits that don't have composio managed auth+- **[White labeling](/tool-router/white-labeling-authentication)**: Customize authentication screens with your branding+</Step>+</Steps>diff --git a/fumadocs/content/tool-router/migration-guide/meta.json b/fumadocs/content/tool-router/migration-guide/meta.jsonnew file mode 100644index 000000000..654fafe51--- /dev/null+++ b/fumadocs/content/tool-router/migration-guide/meta.json@@ -0,0 +1,6 @@+{+ "title": "Migration Guides",+ "pages": [+ "beta-to-stable"+ ]+}diff --git a/fumadocs/content/tool-router/quickstart.mdx b/fumadocs/content/tool-router/quickstart.mdxnew file mode 100644index 000000000..869f655bf--- /dev/null+++ b/fumadocs/content/tool-router/quickstart.mdx@@ -0,0 +1,704 @@+---+title: Quickstart+description: Build an AI agent with access to 1000+ tools+---++Choose how you want to integrate Tool Router:++<Accordions>+<Accordion title="Using Tool Router MCP">++<Tabs items={['Claude Agent SDK', 'OpenAI Agents SDK', 'Vercel AI SDK']}>+<Tab value="Claude Agent SDK">++<Steps>+<Step>+### Install++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```bash+pip install python-dotenv composio claude-agent-sdk+```+</Tab>+<Tab value="TypeScript">+```bash+npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk+```+</Tab>+</Tabs>+</Step>++<Step>+### Create session and run agent++[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.++<Callout type="info">+- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).+- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.+</Callout>++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).++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+import asyncio+from dotenv import load_dotenv+from claude_agent_sdk.client import ClaudeSDKClient+from claude_agent_sdk.types import (+ ClaudeAgentOptions,+ AssistantMessage,+ TextBlock,+ ToolUseBlock,+)+from composio import Composio++load_dotenv()++# Initialize Composio (API key from env var COMPOSIO_API_KEY)+composio = Composio()++# Unique identifier of the user+user_id = "user_123"++# Create a tool router session for the user+session = composio.create(user_id=user_id)++# Configure Claude with Composio MCP server+options = ClaudeAgentOptions(+ system_prompt=(+ "You are a helpful assistant with access to external tools. "+ "Always use the available tools to complete user requests."+ ),+ mcp_servers={+ "composio": {+ "type": "http",+ "url": session.mcp.url,+ "headers": session.mcp.headers,+ }+ },+ permission_mode="bypassPermissions",+)+++async def main():+ print("""+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository and create a notion page with the issues'+""")++ async with ClaudeSDKClient(options) as client:+ # Multi-turn conversation with agentic tool calling+ while True:+ user_input = input("You: ").strip()+ if user_input.lower() == "exit":+ break++ print("\nClaude: ", end="", flush=True)+ try:+ await client.query(user_input)+ async for msg in client.receive_response():+ if isinstance(msg, AssistantMessage):+ for block in msg.content:+ if isinstance(block, ToolUseBlock):+ print(f"\n[Using tool: {block.name}]", end="")+ elif isinstance(block, TextBlock):+ print(block.text, end="", flush=True)+ print()+ except Exception as e:+ print(f"\n[Error]: {e}")+++if __name__ == "__main__":+ asyncio.run(main())+```+</Tab>+<Tab value="TypeScript">+```typescript+import "dotenv/config";+import { query, type Options } from "@anthropic-ai/claude-agent-sdk";+import { Composio } from "@composio/core";+import { createInterface } from "readline/promises";++// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })+const composio = new Composio();++// Unique identifier of the user+const userId = "user_123";++// Create a tool router session for the user+const session = await composio.create(userId);++const options: Options = {+ systemPrompt: `You are a helpful assistant with access to external tools. ` ++ `Always use the available tools to complete user requests.`,+ mcpServers: {+ composio: {+ type: "http",+ url: session.mcp.url,+ headers: session.mcp.headers // Authentication headers for the Composio MCP server+ },+ },+ permissionMode: "bypassPermissions", // Auto-approve tools (demo only - use "default" in production)+};++// Set up interactive terminal input/output for the conversation+const readline = createInterface({ input: process.stdin, output: process.stdout });++console.log(`+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository and create a Google Sheet with the issues'+`);++let isFirstQuery = true;++// Multi-turn conversation with agentic tool calling+while (true) {+ const answer = await readline.question('You: ');+ const input = answer.trim();+ if (input.toLowerCase() === "exit") break;++ process.stdout.write("Claude: ");++ // Use `continue: true` to maintain conversation context+ const queryOptions = isFirstQuery ? options : { ...options, continue: true };+ isFirstQuery = false;++ try {+ for await (const stream of query({ prompt: input, options: queryOptions })) {+ // Only process assistant messages (the SDK also sends result/error messages)+ if (stream.type === "assistant") {+ const { content } = stream.message;+ for (const block of content) {+ if (block.type === "tool_use") {+ process.stdout.write(`\n[Using tool: ${block.name}]`);+ } else if (block.type === "text") {+ process.stdout.write(block.text);+ }+ }+ }+ }+ } catch (error) {+ console.error("\n[Error]:", error instanceof Error ? error.message : error);+ }+ process.stdout.write("\n");+}++readline.close();+```+</Tab>+</Tabs>+</Step>+</Steps>++</Tab>++<Tab value="OpenAI Agents SDK">++<Steps>+<Step>+### Install++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```bash+pip install python-dotenv composio openai-agents+```+</Tab>+<Tab value="TypeScript">+```bash+npm install dotenv @composio/core @openai/agents zod@3+```+</Tab>+</Tabs>+</Step>++<Step>+### Create session and run agent++[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.++<Callout type="info">+- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).+- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.+</Callout>++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).++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from dotenv import load_dotenv+from composio import Composio+from agents import Agent, Runner, HostedMCPTool, SQLiteSession++load_dotenv()++# Initialize Composio (API key from env var COMPOSIO_API_KEY)+composio = Composio()++# Unique identifier of the user+user_id = "user_123"++# Create a Tool Router session for the user+session = composio.create(user_id=user_id)++# Configure OpenAI agent with Composio MCP server+agent = Agent(+ name="Personal Assistant",+ instructions="You are a helpful personal assistant. Use Composio tools to take action.",+ model="gpt-5.2",+ tools=[+ HostedMCPTool(+ tool_config={+ "type": "mcp",+ "server_label": "composio",+ "server_url": session.mcp.url,+ "require_approval": "never",+ "headers": session.mcp.headers,+ }+ )+ ],+)++# Memory for multi-turn conversation+memory = SQLiteSession(user_id)++print("""+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository'+""")++while True:+ user_input = input("You: ").strip()+ if user_input.lower() == "exit":+ break++ print("Assistant: ", end="", flush=True)+ try:+ result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)+ print(f"{result.final_output}\n")+ except Exception as e:+ print(f"\n[Error]: {e}")+```+</Tab>+<Tab value="TypeScript">+```typescript+import "dotenv/config";+import { Composio } from "@composio/core";+import { Agent, run, hostedMcpTool, MemorySession } from "@openai/agents";+import { createInterface } from "readline/promises";++// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })+const composio = new Composio();++// Unique identifier of the user+const userId = "user_123";++// Create a tool router session for the user+const session = await composio.create(userId);++const agent = new Agent({+ name: "Personal Assistant",+ instructions: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: "gpt-5.2",+ tools: [+ hostedMcpTool({+ serverLabel: "composio",+ serverUrl: session.mcp.url,+ headers: session.mcp.headers // Authentication headers for the Composio MCP server+ }),+ ],+});++// Create a memory session for persistent multi-turn conversation+const memory = new MemorySession();++// Set up interactive terminal input/output for the conversation+const readline = createInterface({ input: process.stdin, output: process.stdout });++console.log(`+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository and create a Google Sheet with the issues'+`);++// Multi-turn conversation with agentic tool calling+while (true) {+ const input = (await readline.question("You: ")).trim();+ if (input.toLowerCase() === "exit") break;++ console.log("Assistant: ");++ try {+ // Multi-turn agentic loop: GPT calls tools and reasons until task is complete+ const result = await run(agent, input, { session: memory });+ console.log(`${result.finalOutput}`);+ } catch (error) {+ console.error("\n[Error]:", error instanceof Error ? error.message : error);+ }+}+readline.close();+```+</Tab>+</Tabs>+</Step>+</Steps>++</Tab>++<Tab value="Vercel AI SDK">++<Steps>+<Step>+### Install Composio SDK++```bash+npm install dotenv @composio/core ai @ai-sdk/anthropic @ai-sdk/mcp+```+</Step>++<Step>+### Create session and run agent++[Sessions](/tool-router/users-and-sessions) are ephemeral, user-scoped and manage connections and tools for that user.++<Callout type="info">+- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).+- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.+</Callout>++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).++```typescript+import "dotenv/config";+import { anthropic } from "@ai-sdk/anthropic";+import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";+import { Composio } from "@composio/core";+import { stepCountIs, streamText } from "ai";++// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })+const composio = new Composio();++// Unique identifier of the user+const userId = "user_123";++// Create a tool router session for the user+const { mcp } = await composio.create(userId);++// Create an MCP client to connect to the Composio tool router+const client = await createMCPClient({+ transport: {+ type: "http",+ url: mcp.url,+ headers: mcp.headers, // Authentication headers for the Composio MCP server+ },+});+const tools = await client.tools();++console.log("Summarizing your emails from today");++const stream = await streamText({+ system: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: anthropic("claude-sonnet-4-5"),+ prompt: "Summarize my emails from today",+ stopWhen: stepCountIs(10),+ onStepFinish: (step) => {+ for (const toolCall of step.toolCalls) {+ console.log(`[Using tool: ${toolCall.toolName}]`);+ }+ },+ tools,+});++for await (const textPart of stream.textStream) {+ process.stdout.write(textPart);+}++console.log("\n\n---");+console.log("Tip: If prompted to authenticate, complete the auth flow and run again.");+```+</Step>+</Steps>++</Tab>+</Tabs>++### What just happened?++When you run this agent, Tool Router:+1. **Creates an MCP server** with your session configuration+2. **Searches** for the right tools based on your request+3. **Handles authentication** if needed+4. **Executes tools** and uses a workbench for processing large responses++</Accordion>++<Accordion title="Using Tool router as a native tool">++<Tabs items={['OpenAI', 'Vercel AI SDK']}>+<Tab value="OpenAI">++<Steps>+<Step>+### Install++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```bash+pip install python-dotenv composio composio-openai-agents openai-agents+```+</Tab>+<Tab value="TypeScript">+```bash+npm install @composio/core @composio/openai-agents @openai/agents+```+</Tab>+</Tabs>+</Step>++<Step>+### Create session and use as native tool++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.++<Callout type="info">+- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).+- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.+</Callout>++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from dotenv import load_dotenv+from composio import Composio+from agents import Agent, Runner, SQLiteSession+from composio_openai_agents import OpenAIAgentsProvider++load_dotenv()++# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)+composio = Composio(provider=OpenAIAgentsProvider())++# Unique identifier of the user+user_id = "user_123"++# Create a session and get native tools for the user+session = composio.create(user_id=user_id)+tools = session.tools()++# Configure OpenAI agent with Composio tools+agent = Agent(+ name="Personal Assistant",+ instructions="You are a helpful personal assistant. Use Composio tools to take action.",+ model="gpt-5.2",+ tools=tools,+)++# Memory for multi-turn conversation+memory = SQLiteSession("conversation")++print("""+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository'+""")++while True:+ user_input = input("You: ").strip()+ if user_input.lower() == "exit":+ break++ print("Assistant: ", end="", flush=True)+ try:+ result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)+ print(f"{result.final_output}\n")+ except Exception as e:+ print(f"\n[Error]: {e}")+```+</Tab>+<Tab value="TypeScript">+```typescript+import "dotenv/config";+import { Composio } from "@composio/core";+import { Agent, run, MemorySession } from "@openai/agents";+import { OpenAIAgentsProvider } from "@composio/openai-agents";+import { createInterface } from "readline/promises";++// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)+const composio = new Composio({ provider: new OpenAIAgentsProvider() });++// Unique identifier of the user+const userId = "user_123";+// Create a tool router session for the user+const session = await composio.create(userId);+const tools = await session.tools();++const agent = new Agent({+ name: "Personal Assistant",+ instructions: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: "gpt-5.2",+ tools,+});++// Set up interactive terminal input/output for the conversation+const readline = createInterface({ input: process.stdin, output: process.stdout });+// Create a memory session for persistent multi-turn conversation+const memory = new MemorySession();++console.log(`+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository and create a Google Sheet with the issues'+`);++// Multi-turn conversation with agentic tool calling+while (true) {+ const query = await readline.question("You: ");+ const input = query.trim();++ if (input.toLowerCase() === "exit") break;+ process.stdout.write("Assistant: ");++ try {+ const result = await run(agent, input, { session: memory });+ process.stdout.write(`${result.finalOutput}`);+ } catch (error) {+ console.error("\n[Error]:", error instanceof Error ? error.message : error);+ }+}+readline.close();+```+</Tab>+</Tabs>+</Step>+</Steps>++</Tab>++<Tab value="Vercel AI SDK">++<Steps>+<Step>+### Install++```bash+npm install @composio/core @composio/vercel ai @ai-sdk/anthropic+```+</Step>++<Step>+### Create session and use as native tool++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.++<Callout type="info">+- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://console.anthropic.com/settings/keys).+- `userId` is your user's unique identifier. See [User Management](/docs/user-management) for details.+</Callout>++```typescript+import "dotenv/config";+import { anthropic } from "@ai-sdk/anthropic";+import { Composio } from "@composio/core";+import { VercelProvider } from "@composio/vercel";+import { stepCountIs, streamText } from "ai";++// Initialize Composio with Vercel provider (API key from env var COMPOSIO_API_KEY)+const composio = new Composio({ provider: new VercelProvider() });++// Unique identifier of the user+const userId = "user_123";++// Create a session and get native tools for the user+const session = await composio.create(userId);+const tools = await session.tools();++process.stdout.write("Summarizing your emails from today");+process.stdout.write("\n");++const stream = await streamText({+ system: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: anthropic("claude-sonnet-4-5"),+ prompt: "Summarize my emails from today",+ stopWhen: stepCountIs(10),+ onStepFinish: (step) => {+ for (const toolCall of step.toolCalls) {+ process.stdout.write(`[Using tool: ${toolCall.toolName}]`);+ process.stdout.write("\n");+ }+ },+ tools,+});++for await (const textPart of stream.textStream) {+ process.stdout.write(textPart);+}++process.stdout.write("\n");+process.stdout.write("Tip: If prompted to authenticate, complete the auth flow and run again.");+```+</Step>+</Steps>++</Tab>+</Tabs>++### What just happened?++When you run this agent, Tool Router:+1. **Provides a single tool** to your agent framework+2. **Interprets requests** and **searches** for the right tools internally+3. **Handles authentication** if needed+4. **Executes tools** and uses a workbench for processing large responses++</Accordion>+</Accordions>++## Next steps++<Cards>+ <Card title="Session management" href="/tool-router/users-and-sessions">+ Learn about users, sessions, and how they work.+ </Card>+ <Card title="Tools and toolkits" href="/tool-router/tools-and-toolkits">+ Learn about tools, toolkits, and how to configure them.+ </Card>+ <Card title="Manual authentication" href="/tool-router/manually-authenticating-users">+ Customise the authentication flow for your users.+ </Card>+ <Card title="Using MCP" href="/tool-router/using-with-mcp-clients">+ Connect Tool Router to any MCP-compatible client.+ </Card>+ <Card title="Using as a native tool" href="/tool-router/using-as-a-native-tool">+ Use Tool Router as a native tool with any AI framework.+ </Card>+</Cards>diff --git a/fumadocs/content/tool-router/tools-and-toolkits.mdx b/fumadocs/content/tool-router/tools-and-toolkits.mdxnew file mode 100644index 000000000..dafe9df73--- /dev/null+++ b/fumadocs/content/tool-router/tools-and-toolkits.mdx@@ -0,0 +1,77 @@+---+title: Tools and toolkits+description: Access 800+ integrations through Tool Router+---++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).++## Toolkits and tools++A **toolkit** is a collection of related tools for a service and a **tool** is an individual action your agent can execute.++| Toolkit | Tools |+|---------|-------|+| `github` | `GITHUB_CREATE_A_COMMIT`, `GITHUB_ACTIVITY_LIST_STARGAZERS_FOR_REPO`, `GITHUB_SEARCH_REPO_S`, ... |+| `gmail` | `GMAIL_SEND_EMAIL`, `GMAIL_FETCH_EMAILS`, `GMAIL_CREATE_EMAIL_DRAFT`, ... |+| `linear` | `LINEAR_CREATE_LINEAR_ISSUE`, `LINEAR_UPDATE_ISSUE`, `LINEAR_CREATE_LINEAR_LABEL`, ... |++## Available toolkits++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.++You can also list toolkits programmatically:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+# Returns top 20 toolkits by default+toolkits = composio.toolkits.get()++for toolkit in toolkits:+ print(toolkit.name)+```+</Tab>+<Tab value="TypeScript">+```typescript+// Returns top 20 toolkits by default+const toolkits = await composio.toolkits.get();++for (const toolkit of toolkits) {+ console.log(toolkit.name);+}+```+</Tab>+</Tabs>++For details on browsing tools within toolkits and inspecting schemas, see [Fetching tools and schemas](/docs/fetching-tools).++<Callout type="info">+Some toolkits require you to provide your own credentials. See [Using custom auth configs](/tool-router/using-custom-auth-configs).+</Callout>++<Callout type="info">+Need a toolkit that doesn't exist? [Request it here](https://request.composio.dev/boards/tool-requests).+</Callout>++## Default session behavior++When you create a session, all toolkits are available:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(user_id="user_123")+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123");+```+</Tab>+</Tabs>++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).++<Callout type="info">+Triggers can be used alongside Tool Router to respond to events in connected apps. See [Using triggers](/docs/using-triggers) for setup instructions.+</Callout>diff --git a/fumadocs/content/tool-router/users-and-sessions.mdx b/fumadocs/content/tool-router/users-and-sessions.mdxnew file mode 100644index 000000000..d4a054b01--- /dev/null+++ b/fumadocs/content/tool-router/users-and-sessions.mdx@@ -0,0 +1,254 @@+---+title: Users and sessions+description: Understand how Tool Router scopes tools and connections per user+---++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.++A **session** is an ephemeral configuration that combines:+- Which user's connected accounts to use+- Which toolkits are available+- Which auth configs to use++Tool Router's meta-tools are the same for everyone. The session determines the context they operate within.++## Creating a session++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(user_id="user_123")+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123");+```+</Tab>+</Tabs>++### Enabling toolkits++Restrict the session to specific toolkits:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+# Using array format+session = composio.create(+ user_id="user_123",+ toolkits=["github", "gmail", "slack"]+)++# Using object format with enable key+session = composio.create(+ user_id="user_123",+ toolkits={"enable": ["github", "gmail", "slack"]}+)+```+</Tab>+<Tab value="TypeScript">+```typescript+// Using array format+const session = await composio.create("user_123", {+ toolkits: ["github", "gmail", "slack"],+});++// Using object format with enable key+const session = await composio.create("user_123", {+ toolkits: { enable: ["github", "gmail", "slack"] },+});+```+</Tab>+</Tabs>++### Disabling toolkits++Keep all toolkits enabled except specific ones:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ toolkits={"disable": ["exa", "firecrawl"]}+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ toolkits: { disable: ["exa", "firecrawl"] },+});+```+</Tab>+</Tabs>++### Custom auth configs++Use your own OAuth credentials instead of Composio's defaults:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ auth_configs={+ "github": "ac_your_github_config",+ "slack": "ac_your_slack_config"+ }+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ authConfigs: {+ github: "ac_your_github_config",+ slack: "ac_your_slack_config",+ },+});+```+</Tab>+</Tabs>++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.++## Connected accounts++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.++### Account selection++If a user has multiple connected accounts for the same toolkit, you can specify which one to use:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ connected_accounts={+ "gmail": "ca_work_gmail",+ "github": "ca_personal_github"+ }+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ connectedAccounts: {+ gmail: "ca_work_gmail",+ github: "ca_personal_github",+ },+});+```+</Tab>+</Tabs>++### Precedence++When executing a tool, Tool Router selects the connected account in this order:++1. `connectedAccounts` override if provided in session config+2. `authConfigs` override - finds or creates connection on that config+3. Auth config previously created by Tool Router for this toolkit+4. Creates new auth config using Composio managed auth (tagged as Tool Router created)+5. Error if no Composio managed auth scheme exists for the toolkit++If a user has multiple connected accounts for a toolkit, the most recently connected one is used.++## Session methods++### mcp++Get the MCP server URL to use with any MCP-compatible client.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+mcp_url = session.mcp.url+```+</Tab>+<Tab value="TypeScript">+```typescript+const { mcp } = session;+console.log(mcp.url);+```+</Tab>+</Tabs>++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).++### tools()++Get native tools from the session for use with AI frameworks.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+tools = session.tools()+```+</Tab>+<Tab value="TypeScript">+```typescript+const tools = await session.tools();+```+</Tab>+</Tabs>++### authorize()++Manually authenticate a user to a toolkit outside of the chat flow.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+connection_request = session.authorize("github")++print(connection_request.redirect_url)++connected_account = connection_request.wait_for_connection()+```+</Tab>+<Tab value="TypeScript">+```typescript+const connectionRequest = await session.authorize("github", {+ callbackUrl: "https://myapp.com/callback",+});++console.log(connectionRequest.redirectUrl);++const connectedAccount = await connectionRequest.waitForConnection();+```+</Tab>+</Tabs>++For more details, see [Manually authenticating users](/tool-router/manually-authenticating-users).++### toolkits()++List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+toolkits = session.toolkits()++for toolkit in toolkits.items:+ status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"+ print(f"{toolkit.name}: {status}")+```+</Tab>+<Tab value="TypeScript">+```typescript+const toolkits = await session.toolkits();++toolkits.items.forEach((toolkit) => {+ console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount?.id ?? "Not connected"}`);+});+```+</Tab>+</Tabs>++Returns the first 20 toolkits by default.diff --git a/fumadocs/content/tool-router/using-as-a-native-tool.mdx b/fumadocs/content/tool-router/using-as-a-native-tool.mdxnew file mode 100644index 000000000..494c90b24--- /dev/null+++ b/fumadocs/content/tool-router/using-as-a-native-tool.mdx@@ -0,0 +1,240 @@+---+title: Using as a native tool+description: Use Tool Router as a native tool with any AI framework+---++Tool Router can be used as a single native tool with any AI framework. The tool handles search, authentication, and execution internally.++## Examples for popular frameworks++Jump to examples for:+- [OpenAI](#openai) - Python, TypeScript+- [Vercel AI SDK](#vercel-ai-sdk) - TypeScript++## OpenAI++### Installation++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```bash+pip install python-dotenv composio composio-openai-agents openai-agents+```+</Tab>+<Tab value="TypeScript">+```bash+npm install @composio/core @composio/openai-agents @openai/agents+```+</Tab>+</Tabs>++### Usage++Create a Tool Router session and use it as a native tool with OpenAI Agents SDK:++<Callout type="info">+- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set your `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).+</Callout>++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from dotenv import load_dotenv+from composio import Composio+from agents import Agent, Runner, SQLiteSession+from composio_openai_agents import OpenAIAgentsProvider++load_dotenv()++# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)+composio = Composio(provider=OpenAIAgentsProvider())++# Unique identifier of the user+user_id = "user_123"++# Create a session and get native tools for the user+session = composio.create(user_id=user_id)+tools = session.tools()++# Configure OpenAI agent with Composio tools+agent = Agent(+ name="Personal Assistant",+ instructions="You are a helpful personal assistant. Use Composio tools to take action.",+ model="gpt-5.2",+ tools=tools,+)++# Memory for multi-turn conversation+memory = SQLiteSession("conversation")++# Execute an initial task+print("Fetching GitHub issues from the Composio repository...\n")+try:+ result = Runner.run_sync(+ starting_agent=agent,+ input="Fetch all the open GitHub issues on the @ComposioHQ/composio repository and group them by bugs/features/docs.",+ session=memory,+ )+ print(f"{result.final_output}\n")+except Exception as e:+ print(f"[Error]: {e}")++# Continue with interactive conversation+print("\nWhat else would you like me to do? (Type 'exit' to exit)")++while True:+ user_input = input("You: ").strip()+ if user_input.lower() == "exit":+ break++ print("Assistant: ", end="", flush=True)+ try:+ result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)+ print(f"{result.final_output}\n")+ except Exception as e:+ print(f"\n[Error]: {e}")+```+</Tab>+<Tab value="TypeScript">+```typescript+import "dotenv/config";+import { Composio } from "@composio/core";+import { Agent, run, MemorySession } from "@openai/agents";+import { OpenAIAgentsProvider } from "@composio/openai-agents";+import { createInterface } from "readline/promises";++// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)+const composio = new Composio({ provider: new OpenAIAgentsProvider() });++// Unique identifier of the user+const userId = "user_123";++// Create a session and get native tools for the user+const session = await composio.create(userId);+const tools = await session.tools();++const agent = new Agent({+ name: "Personal Assistant",+ instructions: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: "gpt-5.2",+ tools,+});++// Create a memory session for persistent multi-turn conversation+const memory = new MemorySession();++// Execute an initial task+console.log("Fetching GitHub issues from the Composio repository...\n");+try {+ const initialResult = await run(+ agent,+ "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",+ { session: memory }+ );+ console.log(`${initialResult.finalOutput}\n`);+} catch (error) {+ console.error("[Error]:", error instanceof Error ? error.message : error);+}++// Continue with interactive conversation+const readline = createInterface({ input: process.stdin, output: process.stdout });++console.log(`+What else would you like me to do?+(Type 'exit' to exit)+`);+++while (true) {+ const input = (await readline.question("You: ")).trim();+ if (input.toLowerCase() === "exit") break;++ console.log("Assistant: ");++ try {+ const result = await run(agent, input, { session: memory });+ console.log(`${result.finalOutput}\n`);+ } catch (error) {+ console.error("\n[Error]:", error instanceof Error ? error.message : error);+ }+}+readline.close();+```+</Tab>+</Tabs>++## Vercel AI SDK++### Installation++```bash+npm install @composio/core @composio/vercel ai @ai-sdk/anthropic+```++### Usage++Create a Tool Router session and use it as a native tool with Vercel AI SDK:++<Callout type="info">+- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set your `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://console.anthropic.com/settings/keys).+</Callout>++```typescript+import "dotenv/config";+import { anthropic } from "@ai-sdk/anthropic";+import { Composio } from "@composio/core";+import { VercelProvider } from "@composio/vercel";+import { stepCountIs, streamText } from "ai";++// Initialize Composio with Vercel provider (API key from env var COMPOSIO_API_KEY)+const composio = new Composio({ provider: new VercelProvider() });++// Unique identifier of the user+const userId = "user_123";++// Create a session and get native tools for the user+const session = await composio.create(userId);+const tools = await session.tools();++console.log("Fetching GitHub issues from the Composio repository...");++// Stream the response with tool calling+const stream = await streamText({+ system: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: anthropic("claude-sonnet-4-5"),+ prompt: "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",+ stopWhen: stepCountIs(10),+ onStepFinish: (step) => {+ for (const toolCall of step.toolCalls) {+ console.log(`[Using tool: ${toolCall.toolName}]`);+ }+ },+ tools,+});++for await (const textPart of stream.textStream) {+ process.stdout.write(textPart);+}++console.log("\n\n---");+console.log("Tip: If prompted to authenticate, complete the auth flow and run again.");+```++## Next steps++<Cards>+ <Card title="Quickstart" href="/tool-router/quickstart">+ See both MCP and native tool in action+ </Card>+ <Card title="Using with MCP" href="/tool-router/using-with-mcp-clients">+ Use Tool Router with MCP-compatible clients+ </Card>+ <Card title="Authentication" href="/tool-router/authentication">+ Learn about authentication options+ </Card>+ <Card title="Session management" href="/tool-router/users-and-sessions">+ Configure sessions for your users+ </Card>+</Cards>diff --git a/fumadocs/content/tool-router/using-custom-auth-configs.mdx b/fumadocs/content/tool-router/using-custom-auth-configs.mdxnew file mode 100644index 000000000..280a1f777--- /dev/null+++ b/fumadocs/content/tool-router/using-custom-auth-configs.mdx@@ -0,0 +1,61 @@+---+title: Using custom auth configs+description: Set up auth configs for toolkits without Composio managed authentication+---++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.++<Steps>+<Step>+### Check if a toolkit needs custom credentials++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.+</Step>++<Step>+### Create an auth config++1. Go to **Authentication management** in the [dashboard](https://app.composio.dev)+2. Click **Create Auth Config**+3. Select the toolkit+4. Choose the auth scheme (OAuth2, API Key, etc.)+5. Enter your credentials (client ID, client secret, API key, etc.)+6. Click **Create**++Copy the auth config ID (e.g., `ac_1234abcd`).++<Callout type="info">+For detailed instructions on getting credentials for specific toolkits, see [Custom auth configs](/docs/custom-auth-configs).+</Callout>+</Step>++<Step>+### Use in Tool Router++Pass your auth config ID when creating a session:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ auth_configs={+ "posthog": "ac_your_posthog_config"+ }+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ authConfigs: {+ posthog: "ac_your_posthog_config",+ },+});+```+</Tab>+</Tabs>++Tool Router will now use your auth config when users connect to this toolkit.+</Step>+</Steps>diff --git a/fumadocs/content/tool-router/using-in-chat-authentication.mdx b/fumadocs/content/tool-router/using-in-chat-authentication.mdxnew file mode 100644index 000000000..e9925b5b4--- /dev/null+++ b/fumadocs/content/tool-router/using-in-chat-authentication.mdx@@ -0,0 +1,179 @@+---+title: Using In-chat authentication+description: Let your agent prompt users to connect accounts during conversation+---++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.++## How it works++1. Agent searches for tools via the `COMPOSIO_SEARCH_TOOLS` meta-tool+2. The `COMPOSIO_MANAGE_CONNECTIONS` meta-tool checks connection status, returns Connect Link URL if needed+3. User authenticates, confirms in chat, agent continues++## Configuration++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:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(user_id="user_123")+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123");+```+</Tab>+</Tabs>++### Custom callback URL++Redirect users back to your chat page after they complete authentication:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ manage_connections={+ "callback_url": "https://yourapp.com/chat"+ },+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ manageConnections: {+ callbackUri: "https://yourapp.com/chat",+ },+});+```+</Tab>+</Tabs>++## Examples++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from dotenv import load_dotenv+from composio import Composio+from agents import Agent, Runner, SQLiteSession+from composio_openai_agents import OpenAIAgentsProvider++load_dotenv()++# Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)+composio = Composio(provider=OpenAIAgentsProvider())++# Unique identifier of the user+user_id = "user_123"++# Create a session and get native tools for the user+session = composio.create(user_id=user_id)+tools = session.tools()++# Configure OpenAI agent with Composio tools+agent = Agent(+ name="Personal Assistant",+ instructions="You are a helpful personal assistant. Use Composio tools to take action.",+ model="gpt-5.2",+ tools=tools,+)++# Memory for multi-turn conversation+memory = SQLiteSession("conversation")++print("""+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository'+""")++while True:+ user_input = input("You: ").strip()+ if user_input.lower() == "exit":+ break++ print("Assistant: ", end="", flush=True)+ try:+ result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)+ print(f"{result.final_output}\n")+ except Exception as e:+ print(f"\n[Error]: {e}")+```+</Tab>+<Tab value="TypeScript">+```typescript+import "dotenv/config";+import { Composio } from "@composio/core";+import { Agent, run, MemorySession } from "@openai/agents";+import { OpenAIAgentsProvider } from "@composio/openai-agents";+import { createInterface } from "readline/promises";++// Initialize Composio with OpenAI Agents provider (API key from env var COMPOSIO_API_KEY)+const composio = new Composio({ provider: new OpenAIAgentsProvider() });++// Unique identifier of the user+const userId = "user_123";+// Create a tool router session for the user+const session = await composio.create(userId);+const tools = await session.tools();++const agent = new Agent({+ name: "Personal Assistant",+ instructions: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: "gpt-5.2",+ tools,+});++// Set up interactive terminal input/output for the conversation+const readline = createInterface({ input: process.stdin, output: process.stdout });+// Create a memory session for persistent multi-turn conversation+const memory = new MemorySession();++console.log(`+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository and create a Google Sheet with the issues'+`);++// Multi-turn conversation with agentic tool calling+while (true) {+ const query = await readline.question("You: ");+ const input = query.trim();++ if (input.toLowerCase() === "exit") break;+ process.stdout.write("Assistant: ");++ try {+ const result = await run(agent, input, { session: memory });+ process.stdout.write(`${result.finalOutput}`);+ } catch (error) {+ console.error("\n[Error]:", error instanceof Error ? error.message : error);+ }+}+readline.close();+```+</Tab>+</Tabs>++What this looks like when you run the code:++```+Assistant: What would you like me to do today? Type 'exit' to end the conversation.++> Star the composio repo on GitHub+Assistant: I need you to connect your GitHub account first.+Please click here to authorize: https://connect.composio.dev/link/ln_abc123++> Done\ No newline at end of filediff --git a/fumadocs/content/tool-router/using-with-mcp-clients.mdx b/fumadocs/content/tool-router/using-with-mcp-clients.mdxnew file mode 100644index 000000000..90555b9d0--- /dev/null+++ b/fumadocs/content/tool-router/using-with-mcp-clients.mdx@@ -0,0 +1,405 @@+---+title: Using with MCP clients+description: Use Tool Router as an MCP server with any MCP client+---++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.++## Examples for popular frameworks++Jump to examples for:+- [Claude Agent SDK](#claude-agent-sdk) - Python, TypeScript+- [OpenAI Agents SDK](#openai-agents-sdk) - Python, TypeScript+- [Vercel AI SDK](#vercel-ai-sdk) - TypeScript++## Claude Agent SDK++### Installation++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```bash+pip install python-dotenv composio claude-agent-sdk+```+</Tab>+<Tab value="TypeScript">+```bash+npm install dotenv @composio/core @anthropic-ai/claude-agent-sdk+```+</Tab>+</Tabs>++### Usage++Create a Tool Router session and execute tasks with Claude:++<Callout type="info">+- Set your `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set your `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).+</Callout>++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+import asyncio+from dotenv import load_dotenv+from claude_agent_sdk.client import ClaudeSDKClient+from claude_agent_sdk.types import (+ ClaudeAgentOptions,+ AssistantMessage,+ TextBlock,+ ToolUseBlock,+)+from composio import Composio++load_dotenv()++# Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly)+composio = Composio()++# Unique identifier of the user+user_id = "user_123"+# Create a tool router session for the user+session = composio.create(user_id=user_id)++# Configure Claude with Composio MCP server+options = ClaudeAgentOptions(+ system_prompt=(+ "You are a helpful assistant with access to external tools. "+ "Always use the available tools to complete user requests."+ ),+ mcp_servers={+ "composio": {+ "type": "http",+ "url": session.mcp.url,+ "headers": session.mcp.headers, # Authentication headers for the Composio MCP server+ }+ },+ permission_mode="bypassPermissions", # Auto-approve tools (demo only)+)++async def main():+ print("""+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository and create a notion page with the issues'+""")++ async with ClaudeSDKClient(options) as client:+ # Multi-turn conversation with agentic tool calling+ while True:+ user_input = input("\nYou: ").strip()+ if user_input.lower() == "exit":+ break++ print("\nClaude: ", end="", flush=True)+ try:+ await client.query(user_input)+ async for msg in client.receive_response():+ if isinstance(msg, AssistantMessage):+ for block in msg.content:+ if isinstance(block, ToolUseBlock):+ print(f"\n[Using tool: {block.name}]", end="")+ elif isinstance(block, TextBlock):+ print(block.text, end="", flush=True)+ except Exception as e:+ print(f"\n[Error]: {e}")++if __name__ == "__main__":+ asyncio.run(main())+```+</Tab>+<Tab value="TypeScript">+```typescript+import "dotenv/config";+import { query, type Options } from "@anthropic-ai/claude-agent-sdk";+import { Composio } from "@composio/core";+import { createInterface } from "readline/promises";++// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })+const composio = new Composio();++// Unique identifier of the user+const userId = "user_123";++// Create a tool router session for the user+const session = await composio.create(userId);++const options: Options = {+ systemPrompt: `You are a helpful assistant with access to external tools. ` ++ `Always use the available tools to complete user requests.`,+ mcpServers: {+ composio: {+ type: "http",+ url: session.mcp.url,+ headers: session.mcp.headers // Authentication headers for the Composio MCP server+ },+ },+ permissionMode: "bypassPermissions", // Auto-approve tools (demo only - use "default" in production)+};++// Set up interactive terminal input/output for the conversation+const readline = createInterface({ input: process.stdin, output: process.stdout });++console.log(`+What task would you like me to help you with?+I can use tools like Gmail, GitHub, Linear, Notion, and more.+(Type 'exit' to exit)+Example tasks:+ • 'Summarize my emails from today'+ • 'List all open issues on the composio github repository and create a notion page with the issues'+`);++let isFirstQuery = true;++// Multi-turn conversation with agentic tool calling+while (true) {+ const answer = await readline.question('You: ');+ const input = answer.trim();+ if (input.toLowerCase() === "exit") break;++ process.stdout.write("Claude: ");++ const queryOptions = isFirstQuery ? options : { ...options, continue: true };+ isFirstQuery = false;++ try {+ for await (const stream of query({ prompt: input, options: queryOptions })) {+ // Only process assistant messages (the SDK also sends result/error messages)+ if (stream.type === "assistant") {+ const { content } = stream.message;+ for (const block of content) {+ if (block.type === "tool_use") {+ process.stdout.write(`\n[Using tool: ${block.name}]`);+ } else if (block.type === "text") {+ process.stdout.write(block.text);+ }+ }+ }+ }+ } catch (error) {+ console.error("\n[Error]:", error instanceof Error ? error.message : error);+ }+ process.stdout.write("\n");+}++readline.close();+```+</Tab>+</Tabs>++## OpenAI Agents SDK++### Installation++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```bash+pip install python-dotenv composio openai-agents+```+</Tab>+<Tab value="TypeScript">+```bash+npm install dotenv @composio/core @openai/agents zod@3+```+</Tab>+</Tabs>++### Usage++Create a Tool Router session and execute tasks with OpenAI agents:++<Callout type="info">+- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set `OPENAI_API_KEY` environment variable with your [OpenAI API key](https://platform.openai.com/api-keys).+</Callout>++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from dotenv import load_dotenv+from composio import Composio+from agents import Agent, Runner, HostedMCPTool++load_dotenv()++# Initialize Composio (API key from env var COMPOSIO_API_KEY)+composio = Composio()+# Unique identifier of the user+user_id = "user_123"++# Create a Tool Router session for the user+session = composio.create(user_id=user_id)++# Configure OpenAI agent with Composio MCP server+agent = Agent(+ name="Personal Assistant",+ instructions="You are a helpful personal assistant. Use Composio tools to take action.",+ model="gpt-5.2",+ tools=[+ HostedMCPTool(+ tool_config={+ "type": "mcp",+ "server_label": "composio",+ "server_url": session.mcp.url,+ "require_approval": "never",+ "headers": session.mcp.headers,+ }+ )+ ],+)++# Execute the task+print("Fetching GitHub issues from the Composio repository @ComposioHQ/composio...\n")+try:+ result = Runner.run_sync(+ starting_agent=agent,+ input="Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",+ )+ print(result.final_output)+except Exception as e:+ print(f"[Error]: {e}")++print("\n\n---")+print("Tip: If prompted to authenticate, complete the auth flow and run again.")+```+</Tab>+<Tab value="TypeScript">+```typescript+import "dotenv/config";+import { Composio } from "@composio/core";+import { Agent, hostedMcpTool, run, MemorySession } from "@openai/agents";+import { createInterface } from "readline/promises";++// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })+const composio = new Composio();++// Unique identifier of the user+const userId = "user_123";++// Create a tool router session for the user+const session = await composio.create(userId);++const agent = new Agent({+ name: "Personal Assistant",+ instructions: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: "gpt-5.2",+ tools: [+ hostedMcpTool({+ serverLabel: "composio",+ serverUrl: session.mcp.url,+ headers: session.mcp.headers, // Authentication headers for the Composio MCP server+ }),+ ],+});++// Create a memory session for persistent multi-turn conversation+const memory = new MemorySession();++// Execute an initial task+console.log("Fetching GitHub issues from the Composio repository...\n");+try {+ const initialResult = await run(+ agent,+ "Fetch all the open GitHub issues on the composio repository and group them by bugs/features/docs.",+ { session: memory }+ );+ console.log(`${initialResult.finalOutput}\n`);+} catch (error) {+ console.error("[Error]:", error instanceof Error ? error.message : error);+}++// Continue with interactive conversation+const readline = createInterface({ input: process.stdin, output: process.stdout });++console.log(`+What else would you like me to do?+(Type 'exit' to exit)+`);++while (true) {+ const input = (await readline.question("You: ")).trim();+ if (input.toLowerCase() === "exit") break;++ console.log("Assistant: ");++ try {+ const result = await run(agent, input, { session: memory });+ console.log(`${result.finalOutput}\n`);+ } catch (error) {+ console.error("\n[Error]:", error instanceof Error ? error.message : error);+ }+}+readline.close();+```+</Tab>+</Tabs>++## Vercel AI SDK++### Installation++```bash+npm install dotenv @composio/core ai @ai-sdk/anthropic @ai-sdk/mcp+```++### Usage++Use Tool Router with Vercel AI SDK's `generateText` for single completions:++<Callout type="info">+- Set `COMPOSIO_API_KEY` environment variable with your API key from [Settings](https://platform.composio.dev/?next_page=/settings).+- Set `ANTHROPIC_API_KEY` environment variable with your [Anthropic API key](https://platform.claude.com/settings/keys).+</Callout>++```typescript+import "dotenv/config";+import { anthropic } from "@ai-sdk/anthropic";+import { experimental_createMCPClient as createMCPClient } from "@ai-sdk/mcp";+import { Composio } from "@composio/core";+import { stepCountIs, streamText } from "ai";++// Initialize Composio (API key from env var COMPOSIO_API_KEY or pass explicitly: { apiKey: "your-key" })+const composio = new Composio();++// Unique identifier of the user+const userId = "user_123";++// Create a tool router session for the user+const { mcp } = await composio.create(userId);++// Create an MCP client to connect to the Composio tool router+const client = await createMCPClient({+ transport: {+ type: "http",+ url: mcp.url,+ headers: mcp.headers, // Authentication headers for the Composio MCP server+ },+});+const tools = await client.tools();++console.log("Summarizing your emails from today");++const stream = await streamText({+ system: "You are a helpful personal assistant. Use Composio tools to take action.",+ model: anthropic("claude-sonnet-4-5"),+ prompt: "Summarize my emails from today",+ stopWhen: stepCountIs(10),+ onStepFinish: (step) => {+ for (const toolCall of step.toolCalls) {+ console.log(`[Using tool: ${toolCall.toolName}]`);+ }+ },+ tools,+});++for await (const textPart of stream.textStream) {+ process.stdout.write(textPart);+}++console.log("\n\n---");+console.log("Tip: If prompted to authenticate, complete the auth flow and run again.")+```diff --git a/fumadocs/content/tool-router/white-labeling-authentication.mdx b/fumadocs/content/tool-router/white-labeling-authentication.mdxnew file mode 100644index 000000000..fc4aa4b75--- /dev/null+++ b/fumadocs/content/tool-router/white-labeling-authentication.mdx@@ -0,0 +1,150 @@+---+title: White-labeling authentication+description: Use your own OAuth apps and branded auth screens+---++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".++By default, OAuth screens show Composio's branding. With white-labeling, they'll see your app name and logo.++<Steps>+<Step>+### Create an OAuth app++Create a developer app in the toolkit's developer portal. You'll need the client ID and client secret. Set the callback URL to:++```+https://backend.composio.dev/api/v3/toolkits/auth/callback+```++<Callout type="info">+For step-by-step guides on creating OAuth apps for some toolkits, see [composio.dev/auth](https://composio.dev/auth).+</Callout>+</Step>++<Step>+### Create auth config++Create an auth config in the [Composio dashboard](https://app.composio.dev):++1. Go to **Authentication management** → **Create Auth Config**+2. Select the toolkit (e.g., GitHub)+3. Choose **OAuth2** scheme+4. Enter your **Client ID** and **Client Secret**+5. Select the scopes you need+6. Click **Create**++Copy the auth config ID (e.g., `ac_1234abcd`).++<Callout type="info">+For detailed instructions with screenshots, see [Custom auth configs](/docs/custom-auth-configs).+</Callout>+</Step>++<Step>+### Use in Tool Router++Pass your auth config ID in the session:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ auth_configs={+ "github": "ac_your_github_config"+ },+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ authConfigs: {+ github: "ac_your_github_config",+ },+});+```+</Tab>+</Tabs>++When users connect GitHub, they'll see your OAuth app's name and logo on the consent screen.+</Step>+</Steps>++## Mixing custom and Composio-managed auth++You can white-label some toolkits while using Composio's managed credentials for others:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+session = composio.create(+ user_id="user_123",+ auth_configs={+ "github": "ac_your_github_config",+ "slack": "ac_your_slack_config",+ # gmail, linear, etc. use Composio managed auth+ },+)+```+</Tab>+<Tab value="TypeScript">+```typescript+const session = await composio.create("user_123", {+ authConfigs: {+ github: "ac_your_github_config",+ slack: "ac_your_slack_config",+ // gmail, linear, etc. use Composio managed auth+ },+});+```+</Tab>+</Tabs>++## Custom redirect domain++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.++If you need to hide this URL (for enterprise compliance or complete white-labeling), you can proxy the redirect through your own domain:++1. Set your OAuth app's redirect URI to your domain:+```+https://yourdomain.com/api/composio-redirect+```++2. Create an endpoint that forwards the OAuth callback to Composio:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from fastapi import FastAPI, Request+from fastapi.responses import RedirectResponse++app = FastAPI()+[email protected]("/api/composio-redirect")+def composio_redirect(request: Request):+ # Forward all OAuth parameters to Composio+ composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"+ return RedirectResponse(url=f"{composio_url}?{request.url.query}")+```+</Tab>+<Tab value="TypeScript">+```typescript+// pages/api/composio-redirect.ts (Next.js)+import type { NextApiRequest, NextApiResponse } from "next";++export default function handler(req: NextApiRequest, res: NextApiResponse) {+ // Forward all OAuth parameters to Composio+ const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";+ const params = new URLSearchParams(req.query as Record<string, string>);+ res.redirect(302, `${composioUrl}?${params.toString()}`);+}+```+</Tab>+</Tabs>++3. Update your auth config in the Composio dashboard to use your custom redirect URI.++This makes the OAuth flow go through your domain first, then to Composio for token storage.diff --git a/fumadocs/lib/layout.shared.tsx b/fumadocs/lib/layout.shared.tsxindex 1c310d373..181e2dc7c 100644--- a/fumadocs/lib/layout.shared.tsx+++ b/fumadocs/lib/layout.shared.tsx@@ -42,6 +42,7 @@ export function baseOptions(): BaseLayoutProps {{text: 'Tool Router',url: '/tool-router',+ active: 'nested-url',},{text: 'Toolkits',diff --git a/fumadocs/next.config.mjs b/fumadocs/next.config.mjsindex a2534b653..d987dee09 100644--- a/fumadocs/next.config.mjs+++ b/fumadocs/next.config.mjs@@ -9,13 +9,18 @@ const config = {return [{source: '/',- destination: '/docs/welcome',+ destination: '/docs',permanent: false,},{- source: '/docs',- destination: '/docs/welcome',- permanent: false,+ source: '/docs/welcome',+ destination: '/docs',+ permanent: true,+ },+ {+ source: '/tool-router/overview',+ destination: '/tool-router',+ permanent: true,},];},