Create a new tool router session

Creates a new session for the tool router feature. This endpoint initializes a new session with specified toolkits and their authentication configurations. The session provides an isolated environment for testing and managing tool routing logic with scoped MCP server access.

Authentication

x-api-keystring

API key authentication

Request

This endpoint expects an object.

user_idstringRequired>=1 character

The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address

toolkitsobjectOptional

Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive.

auth_configsmap from strings to stringsOptional

The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed

connected_accountsmap from strings to stringsOptional

The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed

manage_connectionsobjectOptional

Configuration for connection management settings

toolsmap from strings to objectsOptional

Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit

tagslist of enums or objectOptional

Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.

workbenchobjectOptional

Configuration for workbench behavior

Response

Session successfully created. Returns the session ID and MCP server URL for the created session.

session_idstringformat: "toolRouterSessionId"

The identifier of the session

mcpobject

tool_router_toolslist of enums

List of available tools in this session

configobject

The session configuration including user, toolkits, and overrides

1	import requests
2
3	url = "https://backend.composio.dev/api/v3/tool_router/session"
4
5	payload = {
6	"user_id": "user_987654321",
7	"toolkits": { "enable": ["gmail", "slack"] }
8	}
9	headers = {
10	"x-api-key": "<apiKey>",
11	"Content-Type": "application/json"
12	}
13
14	response = requests.post(url, json=payload, headers=headers)
15
16	print(response.json())

1	{
2	"session_id": "trs_987654321",
3	"mcp": {
4	"type": "http",
5	"url": "https://app.composio.dev/tool_router/v3/trs_987654321/mcp"
6	},
7	"tool_router_tools": [
8	"COMPOSIO_SEARCH_TOOLS"
9	],
10	"config": {
11	"user_id": "user_987654321",
12	"toolkits": {
13	"enabled": [
14	"gmail",
15	"slack"
16	]
17	},
18	"auth_configs": {},
19	"connected_accounts": {},
20	"manage_connections": {
21	"enabled": true,
22	"callback_url": "https://your-app.com/auth/callback"
23	},
24	"tools": {},
25	"tags": {
26	"enabled": [
27	"readOnlyHint"
28	],
29	"disabled": [
30	"destructiveHint"
31	]
32	},
33	"workbench": {
34	"proxy_execution_enabled": true,
35	"auto_offload_threshold": 20000
36	}
37	}
38	}

Authentication

Request

Response

Errors