Smithery
tool_router.session.create
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.
Remote smithery/composio
Other tools also called tool_router.session.create?
See providers with this name
Input Schema
{
"type": "object",
"properties": {
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"readOnlyHint",
"destructiveHint",
"idempotentHint",
"openWorldHint"
],
"type": "string"
}
},
{
"type": "object",
"properties": {
"enable": {
"type": "array",
"items": {
"enum": [
"readOnlyHint",
"destructiveHint",
"idempotentHint",
"openWorldHint"
],
"type": "string"
}
},
"disable": {
"type": "array",
"items": {
"enum": [
"readOnlyHint",
"destructiveHint",
"idempotentHint",
"openWorldHint"
],
"type": "string"
}
}
}
}
],
"example": {
"enable": [
"openWorldHint"
],
"disable": [
"destructiveHint"
]
},
"description": "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."
},
"tools": {
"type": "object",
"example": {
"gmail": {
"enable": [
"GMAIL_SEND_EMAIL",
"GMAIL_FETCH_EMAILS"
]
},
"slack": {
"disable": [
"SLACK_ADD_EMOJI"
]
},
"slackbot": {
"tags": {
"enable": [
"destructiveHint"
],
"disable": [
"openWorldHint"
]
}
}
},
"description": "Tool-level configuration per toolkit. Allows you to enable, disable, or filter by tags for specific tools within each toolkit. Every slug passed in `enable` / `disable` must be a valid Composio tool slug for that toolkit — invalid or typo'd slugs fail session creation with a clear error listing which ones didn't match.",
"additionalProperties": {
"anyOf": [
{
"type": "object",
"required": [
"enable"
],
"properties": {
"enable": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"GMAIL_SEND_EMAIL",
"GMAIL_FETCH_EMAILS"
],
"description": "Only these specific tools will be available for this toolkit"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"disable"
],
"properties": {
"disable": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"SLACK_ADD_EMOJI"
],
"description": "These specific tools will be disabled for this toolkit"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"tags"
],
"properties": {
"tags": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"readOnlyHint",
"destructiveHint",
"idempotentHint",
"openWorldHint"
],
"type": "string"
}
},
{
"type": "object",
"properties": {
"enable": {
"type": "array",
"items": {
"enum": [
"readOnlyHint",
"destructiveHint",
"idempotentHint",
"openWorldHint"
],
"type": "string"
}
},
"disable": {
"type": "array",
"items": {
"enum": [
"readOnlyHint",
"destructiveHint",
"idempotentHint",
"openWorldHint"
],
"type": "string"
}
}
}
}
],
"example": {
"enable": [
"openWorldHint"
],
"disable": [
"destructiveHint"
]
},
"description": "MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists."
}
},
"additionalProperties": false
}
]
}
},
"preload": {
"type": "object",
"properties": {
"tools": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"GMAIL_FETCH_EMAILS",
"SLACK_SEND_MESSAGE"
],
"description": "Composio tool slugs to preload. Each slug must be allowed by the session filters (`toolkits`, `tools`, `tags`) — unknown, blocked, meta, or custom slugs return a 400 at session creation."
}
},
"description": "Preload configuration for Composio tools. Controls which tools appear in `session.tools` and the MCP server tool list so the agent can call them directly without going through search first. Custom tools use `preload` on the custom tool/toolkit definition instead. Not supported when multi-account is enabled. Each preloaded tool adds to the agent context window, so keep the list at or under ~20 tools.",
"additionalProperties": false
},
"user_id": {
"type": "string",
"example": "user_123456789",
"minLength": 1,
"description": "The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address"
},
"toolkits": {
"anyOf": [
{
"type": "object",
"required": [
"enable"
],
"properties": {
"enable": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"gmail",
"slack",
"github"
],
"description": "Only these specific toolkits will be enabled"
}
},
"description": "Enable only specific toolkits (allowlist)",
"additionalProperties": false
},
{
"type": "object",
"required": [
"disable"
],
"properties": {
"disable": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"gmail",
"slack"
],
"description": "These specific toolkits will be disabled"
}
},
"description": "Disable specific toolkits (denylist)",
"additionalProperties": false
}
],
"description": "Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive."
},
"workbench": {
"type": "object",
"default": {
"enable": true,
"enable_proxy_execution": true
},
"properties": {
"enable": {
"type": "boolean",
"default": true,
"example": true,
"description": "Set to false to disable the workbench entirely. When disabled, no code execution tools are available in the session."
},
"sandbox_size": {
"enum": [
"standard",
"medium",
"large",
"xlarge"
],
"type": "string",
"default": "standard",
"example": "standard",
"description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard."
},
"auto_offload_threshold": {
"type": "number",
"example": 20000,
"minimum": 0,
"description": "Character threshold for automatic offloading. When workbench response exceeds this threshold, it will be automatically offloaded. Default is picked automatically based on the response size.",
"exclusiveMinimum": true
},
"enable_proxy_execution": {
"type": "boolean",
"default": true,
"example": true,
"description": "Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly."
}
},
"description": "Configuration for workbench behavior",
"additionalProperties": false
},
"auth_configs": {
"type": "object",
"example": {
"gmail": "ac_1a2b3c4d5e6f",
"slack": "ac_7g8h9i0j1k2l"
},
"description": "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",
"additionalProperties": {
"type": "string",
"format": "authConfigId"
}
},
"experimental": {
"type": "object",
"properties": {
"permissions": {
"type": "object",
"required": [
"default"
],
"properties": {
"default": {
"enum": [
"allow_all",
"ask_every_call",
"ask_once_per_session"
],
"type": "string",
"description": "Default elicitation behavior when no override matches. `allow_all` runs every tool without prompting; `ask_every_call` prompts on each invocation; `ask_once_per_session` prompts once and remembers the answer for the rest of the session."
},
"overrides": {
"type": "object",
"description": "Per-tool overrides keyed by `${toolSlug}:${connectedAccountId ?? \"__none__\"}`, plus account-wide overrides keyed by `*:${connectedAccountId ?? \"__none__\"}`. Exact tool overrides take precedence over account-wide overrides. `always_allow` skips the prompt and runs the tool; `always_deny` blocks the tool; `ask_once` prompts once per session (allow/deny) and remembers; `ask_always` prompts on every call with allow-once/allow-session/deny, ignoring any cached session allow. Overrides take precedence over `default`.",
"additionalProperties": {
"enum": [
"always_allow",
"always_deny",
"ask_once",
"ask_always"
],
"type": "string"
}
}
},
"description": "Per-tool elicitation permission config. Default behavior + per-tool always_allow/always_deny overrides. Mutation via PATCH."
},
"custom_tools": {
"type": "array",
"items": {
"type": "object",
"required": [
"slug",
"name",
"description",
"input_schema"
],
"properties": {
"name": {
"type": "string",
"example": "Get Important Emails",
"maxLength": 128,
"minLength": 1,
"description": "Human-readable display name"
},
"slug": {
"type": "string",
"example": "GET_IMPORTANT_EMAILS",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"description": "Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total."
},
"preload": {
"type": "boolean",
"description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions."
},
"description": {
"type": "string",
"example": "Fetch emails marked as important from the last 24 hours",
"maxLength": 5120,
"minLength": 1,
"description": "Used for BM25 search matching and shown to the LLM."
},
"input_schema": {
"type": "object",
"example": {
"type": "object",
"properties": {
"limit": {
"type": "number",
"description": "Max results to return"
}
}
},
"description": "Must have type: \"object\" and a properties field.",
"additionalProperties": {
"nullable": true
}
},
"output_schema": {
"type": "object",
"description": "JSON Schema describing tool output (optional)",
"additionalProperties": {
"nullable": true
}
},
"extends_toolkit": {
"type": "string",
"example": "gmail",
"minLength": 1,
"description": "If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's auth/connection status. If omitted, the tool is standalone (no-auth)."
}
}
},
"description": "Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection."
},
"custom_toolkits": {
"type": "array",
"items": {
"type": "object",
"required": [
"slug",
"name",
"description",
"tools"
],
"properties": {
"name": {
"type": "string",
"example": "E-Commerce API",
"maxLength": 128,
"minLength": 1,
"description": "Display name shown to the LLM and in search results."
},
"slug": {
"type": "string",
"example": "ecommerce",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"description": "Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only."
},
"tools": {
"type": "array",
"items": {
"type": "object",
"required": [
"slug",
"name",
"description",
"input_schema"
],
"properties": {
"name": {
"type": "string",
"example": "Get Customer Orders",
"maxLength": 128,
"minLength": 1,
"description": "Human-readable display name"
},
"slug": {
"type": "string",
"example": "GET_CUSTOMER_ORDERS",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"description": "Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total)."
},
"preload": {
"type": "boolean",
"description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions."
},
"description": {
"type": "string",
"example": "Fetch recent orders for a customer by their email address",
"maxLength": 5120,
"minLength": 1,
"description": "Used for BM25 search matching and shown to the LLM."
},
"input_schema": {
"type": "object",
"example": {
"type": "object",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"description": "Customer email"
}
}
},
"description": "Must have type: \"object\" and a properties field.",
"additionalProperties": {
"nullable": true
}
},
"output_schema": {
"type": "object",
"description": "Optional output schema for the tool response.",
"additionalProperties": {
"nullable": true
}
}
}
},
"maxItems": 100,
"minItems": 1,
"description": "Tools in this custom toolkit"
},
"preload": {
"type": "boolean",
"description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions."
},
"description": {
"type": "string",
"example": "Internal e-commerce API for order management and fulfillment",
"maxLength": 2048,
"minLength": 1,
"description": "Used for BM25 search matching and shown in toolkit connection statuses."
}
}
},
"description": "Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth."
},
"link_url_overwrite": {
"type": "string",
"format": "uri",
"description": "Experimental base URL override for connection link redirects created from this tool-router session. When set, link creation returns `${link_url_overwrite}/link/{link_token}` instead of the default Composio Connect base URL. Use only when your integration needs links to open through a custom Connect host.",
"x-experimental": true
},
"assistive_prompt_config": {
"type": "object",
"properties": {
"user_timezone": {
"type": "string",
"example": "America/New_York",
"description": "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions."
}
},
"description": "Customize assistive prompt generation (e.g., timezone).",
"additionalProperties": false
}
},
"description": "Experimental features - not stable, may be modified or removed in future versions.",
"x-experimental": true
},
"multi_account": {
"type": "object",
"properties": {
"enable": {
"type": "boolean",
"example": true,
"description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration."
},
"max_accounts_per_toolkit": {
"type": "integer",
"example": 5,
"maximum": 10,
"minimum": 2,
"description": "Maximum number of connected accounts allowed per toolkit. Must be between 2 and 10."
},
"require_explicit_selection": {
"type": "boolean",
"example": false,
"description": "When true, the agent must explicitly select which account to use. When false (default), the first/default account is used automatically."
}
},
"description": "Configure multi-account behavior. When enabled, users can connect multiple accounts per toolkit.",
"additionalProperties": false
},
"connected_accounts": {
"type": "object",
"example": {
"github": "ca_3m4n5o6p7q8r"
},
"description": "Per-toolkit connected account override (single nano-ID). Each connected account must exist (not deleted or disabled) and belong to the same `user_id` as the session.",
"additionalProperties": {
"type": "string",
"example": "ca_3m4n5o6p7q8r"
}
},
"manage_connections": {
"type": "object",
"default": {
"enable": true,
"enable_connection_removal": true,
"enable_wait_for_connections": false
},
"properties": {
"enable": {
"type": "boolean",
"default": true,
"example": true,
"nullable": true,
"description": "Whether to enable the connection manager for automatic connection handling. If true, we will provide a tool your agent can use to initiate connections to toolkits if it doesnt exist. If set to false, then you have to manage connections manually."
},
"callback_url": {
"type": "string",
"format": "uri",
"example": "https://your-app.com/auth/callback",
"description": "The URL to redirect to after a user completes authentication for a connected account. This allows you to handle the auth callback in your own application."
},
"enable_connection_removal": {
"type": "boolean",
"default": true,
"nullable": true,
"description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true."
},
"enable_wait_for_connections": {
"type": "boolean",
"default": false,
"example": false,
"nullable": true,
"description": "When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is available for agents to poll connection status after sharing auth URLs. Default is false (disabled). May not work reliably with GPT models."
}
},
"description": "Configuration for connection management settings",
"additionalProperties": false
}
}
}