Tool Router Quick Start | Composio Docs

Tool Router automatically discovers, authenticates, and executes the right tools for any task. It’s an experimental feature that handles the entire workflow—from finding relevant tools across 500+ integrations to managing authentication and parallel execution.

This is what powers complex agentic products like Rube.

Quick Start

Create a presigned URL for each user session. This URL exposes Tool Router capabilities through the Model Context Protocol (MCP).

1 from composio import Composio
2 composio = Composio()
3 
4 userId = "hey@example.com"
5 # Create a tool router session
6 session = composio.experimental.tool_router.create_session(
7     user_id=userId,
8 )
9 
10 mcpUrl = session['url']

Now you can use the MCP URL in any MCP client, you can see how it lists tools inside the inspector here

What are sessions?

A session encapsulates a single conversation between a user and the language model.

Sessions are designed for security. Each presigned URL contains user authentication credentials and should never be stored long-term or exposed to the client. Generate a new URL for each conversation.

How Tool Router Works

The Tool Router executes a three-phase workflow:

1. Discovery
Searches across all available tools to find ones matching your task. Returns relevant toolkits with their descriptions, schemas, and connection status.

2. Authentication
Checks if the user has an active connection to the required toolkit. If not, creates an auth config and returns a connection URL using Auth Link. The user completes authentication through this link.

3. Execution
Loads authenticated tools into context and executes them. Supports parallel execution across multiple tools for efficiency.

Available Tools

The router exposes six meta tools through MCP. These tools orchestrate the complete workflow from discovery to execution:

COMPOSIO_SEARCH_TOOLS

Discovers tools across 500+ integrated apps based on task description.

Call this first in any workflow. Returns toolkits and tools with slugs, descriptions, input schemas, connection status, and related tools. Includes memory of previous interactions to improve future searches.

COMPOSIO_CREATE_PLAN

Generates step-by-step execution plans for any workflow.

Call after COMPOSIO_SEARCH_TOOLS. Outputs structured plans with workflow steps, complexity assessment, decision trees for conditional logic, failure handling strategies, and output format specifications.

COMPOSIO_MANAGE_CONNECTIONS

Creates and manages connections to external apps.

Call when COMPOSIO_SEARCH_TOOLS finds no active connection. Supports OAuth (default and custom), API keys, bearer tokens, and basic auth. Returns OAuth redirect URLs when needed and handles connection refresh.

COMPOSIO_MULTI_EXECUTE_TOOL

Executes up to 20 tools in parallel across different apps.

Primary execution tool for running discovered tools. Returns structured outputs with automatic error handling and retry logic.

COMPOSIO_REMOTE_WORKBENCH

Persistent Python sandbox for processing large responses and bulk operations.

Use for processing remote file data or scripting bulk executions. Provides a Jupyter notebook environment with pre-loaded helpers (run_composio_tool, invoke_llm, web_search). State persists across executions with a 4-minute timeout.

COMPOSIO_REMOTE_BASH_TOOL

Executes bash commands in a remote sandbox.

Use for processing large responses saved to remote storage and file system operations. Runs from /home/user with access to shell tools (jq, awk, sed, grep). Default timeout is 300 seconds.

Customizing the Tool Router

Restricting Toolkits

Control which toolkits are available by specifying them during session creation. This limits which apps your users can access.

1 session = composio.experimental.toolRouter.createSession("hey@example.com", {
2   toolkits: ["github", "slack"],
3 })

Manual Connection Management

You can manually manage connections, this is advanced and still a bit of work in progress.

To manually manage connections, you can set manuallyManageConnections to true and limit the toolkits you want to use.

Once you pass the auth config id, you can use our regular functions to connect accounts and check authentication status.

1 // Access the experimental ToolRouter
2 const session = await composio.experimental.toolRouter.createSession("hey@example.com", {
3   toolkits: [{ toolkit: 'gmail', authConfigId: 'ac_nnn' }],
4   manuallyManageConnections: true,
5 });

Feedback

This is still very experimental and work in progress, you can expect the contracts to change and improve as we iterate on this. That said we would love to hear your feedback on this

Give us feedback on this github discussion here