141
Do not force advanced requests through first-time setup. Route them to current documentation:
142
143
- Session scoping, account selection, callbacks, direct tools, and sandbox controls: `configuring-sessions.md`
144
+- Asking the user before a tool runs: `approvals.md`, covered in [Require approval before tools run](#require-approval-before-tools-run)
145
+- Blocking tool calls, tool results, or prompt injection: `firewall.md`, covered in [Block calls and results with Firewall](#block-calls-and-results-with-firewall)
146
+- Adding a remote MCP server as a toolkit: `extending-sessions/custom-mcp.md`, covered in [Add a remote MCP server](#add-a-remote-mcp-server)
147
+- Custom tools and toolkits that run in the application, or proxy execution: the other `extending-sessions` guides
148
- Custom connection UI: `manually-authenticating.md`
149
- Triggers and webhooks: `triggers.md` and the setting-up-triggers guides
146
-- Custom MCP servers, tools, toolkits, or proxy execution: the `extending-sessions` guides
150
- Legacy direct execution, MCP servers, or Tool Router migrations: the migration and sessions guides
151
- White labeling and custom OAuth apps: `white-labeling-authentication.md`
152
153
"Tool Router" is the former name for sessions. Treat direct execution as a migration path, not the default for new agent integrations.
154
155
+Approvals, Firewall, and Custom MCP are experimental. Fetch their current page before writing code, check the installed SDK version against the minimum the page names, and copy the documented call shape for the requested language. Add them only when the request or inspected code asks for that control. A request like "ask before sending", "confirm before writes", or "human in the loop" asks for Approvals. A request like "never let the agent email pricing" or "stop prompt injection" asks for Firewall.
156
+
157
+### Require approval before tools run
158
+
159
+Approvals make Composio pause a tool call and ask the user before it runs. Composio doesn't run the tool. It returns an elicitation, then runs the tool when the call comes back with the user's answer.
160
+
161
+Choose the gated tools when you create the session:
162
+
163
+- By tag, session-wide: `tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]}` in Python, `tags: { requireApproval: [...] }` in TypeScript.
164
+- By tag, per toolkit: set `tools.<toolkit>.tags`. It replaces the session-wide `tags` for that toolkit, including blocked tags, so list everything that toolkit still needs.
165
+- By tool: set `tools.<toolkit>.require_approval` (`requireApproval` in TypeScript) to exact tool slugs. Prefer explicit slugs for anything that must always be gated: Composio assigns tags on a best-effort basis.
166
+
167
+Handle the pause in the application's tool loop:
168
+
169
+1. Run tools with `session.execute()`. The SDK's `handle_tool_calls` and framework providers don't handle approvals yet.
170
+2. Catch `ToolInputRequiredError` (Python, from `composio.exceptions`) or `ComposioToolInputRequiredError` (TypeScript). Over the API, the response has `"result_type": "input_required"`.
171
+3. Show the user each entry in `input_requests`: its `message`, and a form built from its `requested_schema`. Build the form from the schema, since choices vary. One call can return several questions, for example from `COMPOSIO_MULTI_EXECUTE_TOOL`.
172
+4. Retry the same call with `input_responses` (each `{"action": "accept", "content": {...}}`, keyed by question ID) and the returned `request_state`.
173
+
174
+An **Always approve** answer lasts for the rest of the session for that tool on the same connected account.
175
+
176
+Over MCP, clients that support elicitation ask the user themselves. Clients without elicitation support get the call denied, unless the session sets `experimental.no_elicitation_support_fallback` to `"allow"`. Only suggest that fallback when the developer accepts running those tools without approval.
177
+
178
+Tell the developer about the documented limits when they matter: Workbench and bash scripts can call tools the approval check misses (disable the sandbox if approval must never be skipped), and `session.proxy_execute()` is disabled for a toolkit with any approval-gated tool.
179
+
180
+### Block calls and results with Firewall
181
+
182
+Firewall blocks tool calls the agent shouldn't make and tool results it shouldn't read. Configure it with session `hooks`. Each hook needs a unique `id`, a `type`, an `applies_to` (`appliesTo` in TypeScript) of toolkit slugs or `"all"`, and a `handler`.
183
+
184
+- `before_execute` with a `condition_check` handler blocks a call before it runs, such as emailing internal pricing to a customer.
185
+- `after_execute` with a `condition_check` handler blocks a result before the agent reads it, such as an email that contains an API key.
186
+- `after_execute` with a `prompt_injection_check` handler blocks results that contain prompt injection. It works only in `after_execute`.
187
+
188
+Write each `condition` as a description of what to block, not as an instruction to the agent. "Sharing internal pricing with anyone outside acme.com" works. "Don't share internal pricing" does not.
189
+
190
+A blocked call returns `result_type` `blocked`, the error `Blocked by session policy`, and a `block_reason` and `hook_results` naming the hook. This is a policy outcome, not a tool or auth failure. Don't retry it or reconnect the account.
191
+
192
+`session.update(hooks=[...])` replaces the whole hook list, so include every hook to keep. Hooks don't run on meta tools themselves, but they do check tool calls made through multi-execute, Workbench scripts, and proxy calls. Firewall is a paid-plan feature, and with Zero Data Retention the classifier judges each call without earlier session context.
193
+
194
+### Add a remote MCP server
195
+
196
+Custom MCP adds a remote MCP server as a Composio toolkit, so its tools sit next to Composio's toolkits in a session. Use it for an MCP server on a public HTTPS URL. Use Custom Tools and Toolkits instead for functions that run inside the application.
197
+
198
+1. Create the toolkit with `composio.experimental.custom_toolkits.create()` in Python or `composio.experimental.customToolkits.create()` in TypeScript. Pass `name`, the final MCP endpoint as `app_url` (no redirects, no keys in the URL), `auth_schemes`, and `user_id`.
199
+2. Store the returned `CUSTOM_*` slug. Never construct it yourself.
200
+3. If a private toolkit needs auth, send its user to the returned `connect_link.redirect_url`. `connect_link` is `null` for shared and no-auth toolkits. Tools sync on creation for no-auth servers, and when the first account connects otherwise.
201
+4. Add the slug to a session's toolkits. The agent finds the tools with `COMPOSIO_SEARCH_TOOLS`.
202
+
203
+Choose `user_id` deliberately: `"all"` shares the toolkit with every user in the project, and a user ID makes it private to that user. Choose `auth_schemes` mode `NO_AUTH`, `API_KEY` (a header containing `{{generic_api_key}}`), or `DCR_OAUTH` (with a `discovery_url`). `app_url`, `auth_schemes`, and `user_id` can't change later: delete and create the toolkit again.
204
+
205
+Know the limits before promising a design: remote servers only (no local or STDIO), at most 500 tools, OAuth only through Dynamic Client Registration, and no automatic resync. Call `sync()` when the server's tools change. `upsert()` is deprecated: new code uses `create()` and `update()`.
206
+
207
## Verify setup when relevant
208
209
For a first-time setup or integration request, success means a programmatic, safe, read-only tool call from the developer's real execution path returns an actual provider result and a non-empty Composio log ID.