Tool Router Quick Start

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

$
pip install composio_openai_agents openai-agents

$
export COMPOSIO_API_KEY="your-api-key"

1
import asyncio
2
import os
3
from composio import Composio
4
from composio_openai_agents import OpenAIAgentsProvider
5
from agents import Agent, Runner, HostedMCPTool
6
7
async def main() -> None:
8
# Initialize Composio and create Tool Router session
9
composio = Composio(
10
 api_key=os.getenv("COMPOSIO_API_KEY"), # Uses env var by default
11
 provider=OpenAIAgentsProvider()
12
)
13
session = composio.experimental.tool_router.create_session(
14
 user_id="user@example.com",
15
 toolkits=["gmail", "github"] # Optional: Limit available toolkits
16
)

1
# Set up OpenAI agent with Tool Router MCP endpoint
2
agent = Agent(
3
 name="Assistant",
4
 instructions="You are a helpful assistant that can access Gmail and GitHub. "
5
 "Help users fetch emails, create issues, manage pull requests, and more.",
6
 tools=[
7
 HostedMCPTool(
8
 tool_config={
9
 "type": "mcp",
10
 "server_label": "tool_router",
11
 "server_url": session['url'],
12
 "require_approval": "never",
13
 }
14
 )
15
 ],
16
)

1
# Execute the agent
2
result = await Runner.run(
3
 agent, 
4
 "Fetch the contributors to composiohq/composio github repository and email the list to user@example.com"
5
)
6
print(result.final_output)
7
8
asyncio.run(main())

Visualizing Tool Router in MCP Inspector

You can inspect the session URL in any MCP client. Here’s what it looks like in the MCP Inspector:

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.

These phases are orchestrated through a set of meta tools, which handle search, planning, connection management, execution, and remote workbench.

Works with any MCP client

The session URL you created is a standard MCP endpoint. Use it with any framework that supports MCP:

Vercel AI SDK

Use experimental_createMCPClient with StreamableHTTPClientTransport to integrate with Next.js apps

Claude

Connect remote MCP servers through Anthropic’s MCP connector API

LangChain

Load Tool Router tools using langchain_mcp_adapters for Python workflows

Customization

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.tool_router.create_session(
2
 user_id="user@example.com",
3
 toolkits=["github", "slack", "gmail"]
4
)

Manual connection management

For advanced use cases, you can manually manage connections:

1
session = composio.experimental.tool_router.create_session(
2
 user_id="user@example.com",
3
 toolkits=[{"toolkit": "gmail", "auth_config_id": "ac_nnn"}],
4
 manually_manage_connections=True
5
)

When you pass the auth config ID, you can use regular Composio functions to connect accounts and check authentication status.

Feedback

This is still very experimental and work in progress, and 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.