Tool Router

Intelligent tool routing and connection management

Tool Router is an experimental feature that provides intelligent tool routing, automatic connection management, and MCP server integration.

Tool Router creates isolated sessions for users with automatic connection management, toolkit access control, and MCP server support.

Quick Start

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

const composio = new Composio({ apiKey: 'your-key' });

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github', 'slack'],
  manageConnections: true
});

console.log('Session ID:', session.sessionId);
console.log('MCP URL:', session.mcp.url);

const tools = await session.tools();

Creating Sessions

create()

Create a new Tool Router session for a user:

async create(
  userId: string,
  config?: ToolRouterCreateSessionConfig
): Promise<ToolRouterSession>

userId · string · required

External user ID from your database

config · ToolRouterCreateSessionConfig

Show properties

toolkits · string[] | ToolkitConfig[]

Toolkits to enable for this session

manageConnections · boolean · default: false

Enable automatic connection management UI

tools · ToolsConfig

Enable/disable specific tools per toolkit

tags · string[]

Filter tools by tags

authConfigs · string[]

Specific auth configs to use

connectedAccounts · string[]

Pre-connected accounts

workbench · WorkbenchConfig

Enable workbench mode for testing

Basic Session

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github', 'slack']
});

With Connection Management

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github'],
  manageConnections: true // Enables connection UI
});

// User can connect accounts via MCP UI
console.log(`Connect at: ${session.mcp.url}`);

With Tool Restrictions

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github'],
  tools: {
    github: {
      disabled: ['GITHUB_DELETE_REPO'] // Disable dangerous tools
    }
  }
});

With Tags

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github'],
  tags: ['important'] // Only include important tools
});

Session Object

The session object provides access to tools, connections, and MCP:

interface ToolRouterSession {
  sessionId: string; // Unique session identifier
  mcp: { // MCP server config
    type: 'streamable_http';
    url: string;
    headers: Record<string, string>;
  };
  tools: () => Promise<WrappedTools>; // Get tools for your provider
  authorize: (toolkit: string) => Promise<ConnectionRequest>; // Authorize toolkit
  toolkits: () => Promise<ToolkitConnectionState[]>; // List toolkits
}

Using Sessions

get tools()

Get tools wrapped for your provider:

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github']
});

const tools = await session.tools();
// Returns tools in your provider's format (OpenAI, Anthropic, etc.)

authorize()

Initiate toolkit authorization:

const connectionRequest = await session.authorize('github', {
  callbackUrl: 'https://your-app.com/callback'
});

if (connectionRequest.redirectUrl) {
  console.log(`User should visit: ${connectionRequest.redirectUrl}`);
  
  const connection = await connectionRequest.waitForConnection();
  console.log('Connected!', connection.id);
}

toolkits()

List toolkit connection states:

const toolkits = await session.toolkits();

toolkits.items.forEach(toolkit => {
  console.log(toolkit.slug, toolkit.name);
  
  if (toolkit.connection) {
    console.log('Connected:', toolkit.connection.isActive);
  } else if (!toolkit.isNoAuth) {
    console.log('Not connected');
  }
});

Using Existing Sessions

use()

Retrieve an existing session:

const session = await composio.toolRouter.use('session_abc123');

const tools = await session.tools();
const toolkits = await session.toolkits();

MCP Server Integration

Each session provides an MCP server URL:

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github'],
  manageConnections: true
});

console.log('MCP URL:', session.mcp.url);
console.log('Headers:', session.mcp.headers);

// Use with Claude Desktop, Cursor, or other MCP clients

MCP Client Configuration

For Claude Desktop or Cursor:

{
  "mcpServers": {
    "composio-session": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "${session.mcp.url}"
      ],
      "env": {
        "x-api-key": "your-composio-api-key"
      }
    }
  }
}

Tool Access Control

Control which tools are available:

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github'],
  tools: {
    github: {
      // Only enable specific tools
      enabled: [
        'GITHUB_GET_REPOS',
        'GITHUB_CREATE_ISSUE',
        'GITHUB_LIST_ISSUES'
      ]
    }
  }
});

// Or disable specific tools
const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github'],
  tools: {
    github: {
      disabled: [
        'GITHUB_DELETE_REPO',
        'GITHUB_DELETE_FILE'
      ]
    }
  }
});

Workbench Mode

Enable workbench mode for testing:

const session = await composio.toolRouter.create('user_123', {
  toolkits: ['github'],
  workbench: {
    enabled: true
  }
});

// Provides a web UI for testing tools
console.log(`Test tools at: ${session.mcp.url}/workbench`);

Complete Example

import { Composio } from '@composio/core';
import { OpenAIProvider } from '@composio/openai';
import OpenAI from 'openai';

const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY!,
  provider: new OpenAIProvider()
});

const openai = new OpenAI();

async function runAgentWithSession(userId: string, userMessage: string) {
  // Create session
  const session = await composio.toolRouter.create(userId, {
    toolkits: ['github', 'slack'],
    manageConnections: true,
    tools: {
      github: {
        disabled: ['GITHUB_DELETE_REPO']
      }
    }
  });

  // Get tools
  const tools = await session.tools();

  // Check connections
  const toolkits = await session.toolkits();
  const githubToolkit = toolkits.items.find(t => t.slug === 'github');
  
  if (!githubToolkit?.connection?.isActive) {
    const connection = await session.authorize('github');
    console.log(`Connect GitHub at: ${connection.redirectUrl}`);
    await connection.waitForConnection();
  }

  // Run agent
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    tools,
    messages: [{ role: 'user', content: userMessage }]
  });

  return response.choices[0].message.content;
}

const result = await runAgentWithSession(
  'user_123',
  'Create a GitHub issue and notify team in Slack'
);

Best Practices

1. Session Reuse: Store session IDs and reuse them
2. Connection Management: Enable manageConnections for user-driven auth
3. Tool Restrictions: Disable dangerous tools in production
4. Error Handling: Handle connection failures gracefully
5. Session Cleanup: Delete sessions when no longer needed

Limitations

• Sessions are experimental and API may change
• MCP integration requires MCP-compatible clients
• Some features may not work in all environments

Next Steps

MCP

Learn about MCP servers

Tools API

Learn about tools

Connected Accounts

Manage connections

Composio Class

Main SDK reference