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

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 enabled toolkits (allowlist) or disabled 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

connectionsobjectOptional

Configuration for connection management settings

toolsobjectOptional

Configuration for tool overrides and filtering

executionobjectOptional

Configuration for workbench behavior including security restrictions and execution limits

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

Allowed values:

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_123456789",
7	"toolkits": { "enabled": ["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_123456789",
3	"mcp": {
4	"type": "HTTP",
5	"url": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"
6	},
7	"tool_router_tools": [
8	"COMPOSIO_SEARCH_TOOLS"
9	],
10	"config": {
11	"user_id": "string",
12	"toolkits": {
13	"enabled": [
14	"string"
15	]
16	},
17	"auth_configs": {},
18	"connected_accounts": {},
19	"connections": {
20	"auto_manage_connections": true,
21	"infer_scopes_from_tools": true,
22	"callback_uri": "string"
23	},
24	"tools": {
25	"overrides": {},
26	"filters": {
27	"tags": {
28	"include": [
29	"string"
30	],
31	"exclude": [
32	"string"
33	]
34	}
35	}
36	},
37	"execution": {
38	"proxy_execution_enabled": true,
39	"timeout_seconds": 1.1
40	}
41	}
42	}

Authentication

Request

Response

Errors