@devries-cameron20 / composio Mirror · read-only / commits / fed39f8ca
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

docs(skills): cover Approvals, Firewall, and Custom MCP in the composio skill (#5214)

## Summary Palash asked to update the public `composio` skill so it covers the newer features (Approvals, Custom MCP, and Firewall), written to the repo's `good-docs-writing` guide. - `skills/composio/references/platform.md`: new sections on requiring approval before tools run, blocking calls and results with Firewall hooks, and adding a remote MCP server as a Custom MCP toolkit. Each section covers when to use the feature, the exact identifiers from the current docs pages, and the documented limits. The advanced-work routing list now points to `approvals.md`, `firewall.md`, and `extending-sessions/custom-mcp.md`. - `skills/composio/references/errors.md`: treat `input_required` and `blocked` results as session policy outcomes, not auth failures, and add Custom MCP "tools missing" troubleshooting. - `skills/composio/SKILL.md`: description and routing mention the new features; stable rule 9 keeps them out of the first path unless requested, and says to use the documented feature instead of prompt-level substitutes when they are requested. - `docs/content/docs/using-composio-skill.mdx`: three rows in "What the skill helps with" linking Approvals, Firewall, and Custom MCP. All identifiers come from `docs/content/docs/approvals.mdx`, `firewall.mdx`, and `extending-sessions/custom-mcp.mdx`. No em-dashes. ## Checks - `bun run validate:agent-skills`: passed - `bun run validate:skill-routing`: passed - `docs`: `bun test tests/static/knowledge-search.test.ts tests/static/dashboard-links.test.ts` (45 pass), `bun run lint:links` (0 errors) Please review the full diff before merging. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Palash Kala [zen] <palash@composio.dev> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

composio-zen[bot] committed Nov 9, 2026 at 15:09 UTC fed39f8caf150bc4057e4cbce49a834e540d4e61
4 files changed +74 -5
docs/content/docs/using-composio-skill.mdx
+3
@@ -33,6 +33,9 @@ The skill routes the agent based on what you are building:
33 | Add app integrations to a product | Composio SDK and sessions |
34 | Use apps from your own coding agent | Agent plugin, CLI, or MCP |
35 | Add Composio to an existing MCP client | Composio Connect |
36 +| Ask the user before tools run | [Approvals](/docs/approvals) |
37 +| Block risky tool calls, sensitive results, or prompt injection | [Firewall](/docs/firewall) |
38 +| Use tools from your own remote MCP server | [Custom MCP](/docs/extending-sessions/custom-mcp) |
39 | Diagnose a connection or tool-call error | Current docs and public support knowledge |
40
41 For product integrations, the agent should preserve your framework and application identity model rather than replacing them with a standalone demo. It should use your stable application user ID when creating Composio sessions and keep your Composio API key on the server.
skills/composio/SKILL.md
+4 -4
@@ -1,6 +1,6 @@
1 ---
2 name: composio
3 -description: Route and complete Composio work across Composio For You and Composio Platform. Use when the user mentions Composio; wants an agent to use apps such as Gmail, Slack, GitHub, Notion, Calendar, or Linear; needs first-time setup, an SDK or MCP integration, CLI operation, migration guidance, current documentation, or help diagnosing a connection or tool call.
3 +description: Route and complete Composio work across Composio For You and Composio Platform. Use when the user mentions Composio; wants an agent to use apps such as Gmail, Slack, GitHub, Notion, Calendar, or Linear; needs first-time setup, an SDK or MCP integration, CLI operation, tool approvals, Firewall hooks, a custom MCP server, migration guidance, current documentation, or help diagnosing a connection or tool call.
4 ---
5
6 # Composio
@@ -39,8 +39,8 @@ Do not turn an explanation, documentation lookup, or narrow bug fix into onboard
39 ## 3. Load only the relevant guidance
40
41 - For You: read [Composio For You](references/for-you.md).
42 -- Platform: read [Composio Platform](references/platform.md).
43 -- Provider, connection, or execution failure: also read [Errors and provider gotchas](references/errors.md).
42 +- Platform: read [Composio Platform](references/platform.md). It also covers Approvals, Firewall, and Custom MCP.
43 +- Provider, connection, or execution failure, including a call paused for approval or blocked by Firewall: also read [Errors and provider gotchas](references/errors.md).
44
45 ## Complete the selected job
46
@@ -59,7 +59,7 @@ Do not turn an explanation, documentation lookup, or narrow bug fix into onboard
59 6. Use sessions for new Platform integrations. Preserve the application's existing user identity and agent architecture.
60 7. Keep credentials out of source control, URLs, logs, chat, and command output.
61 8. Get the log or request ID before diagnosing a failed tool call.
62 -9. Prefer the smallest configuration that completes the current job. Keep toolkit filters, tag policies, sandbox controls, custom auth, provider-specific hardening, and other advanced options out of the first path unless the request or existing code requires them.
62 +9. Prefer the smallest configuration that completes the current job. Keep toolkit filters, tag policies, approvals, Firewall hooks, Custom MCP toolkits, sandbox controls, custom auth, provider-specific hardening, and other advanced options out of the first path unless the request or existing code requires them. When the request does ask for one, such as "ask before sending" or "block prompt injection", use the documented feature instead of building a substitute in prompts or application code.
63 10. Do not invent repository facts. Never claim that a file, framework, environment loader, identity field, agent path, or dependency exists until it was provided or inspected. If codebase context is unavailable, state the unknown and ask for access or one necessary detail.
64 11. In SDK or API examples, use exact identifiers and call shapes from a current public page or schema. Copy the documented shape for the requested language instead of translating names between TypeScript and Python; if a required detail is not documented, explain the behavior without inventing code.
65
skills/composio/references/errors.md
+11
@@ -22,6 +22,17 @@ Never guess a slug. In a Platform session, discover tools through the session me
22
23 For legacy manual execution, a missing tool may be a toolkit-version problem. Fetch current migration and execution docs rather than assuming the provider lacks the operation. New session integrations should use runtime discovery.
24
25 +## Tool call paused or blocked by session policy
26 +
27 +Some results are the session working as configured, not failures. Check the result type before diagnosing auth or the provider:
28 +
29 +- **`input_required`** (`ToolInputRequiredError` in Python, `ComposioToolInputRequiredError` in TypeScript): an [Approvals](https://docs.composio.dev/docs/approvals.md) rule gated the tool. It didn't run. Ask the user, then retry with `input_responses` and `request_state`. Over MCP, a client without elicitation support gets these calls denied.
30 +- **`blocked`** with `Blocked by session policy`: a [Firewall](https://docs.composio.dev/docs/firewall.md) hook matched. `block_reason` and `hook_results` name the hook. Don't reconnect the account or retry the same call. Change the request, or change the hook if it blocked something it shouldn't.
31 +
32 +## Custom MCP tools missing
33 +
34 +If a `CUSTOM_*` toolkit synced but its tools don't appear in search, list the toolkit's tools directly or fetch them with `COMPOSIO_GET_TOOL_SCHEMAS`, then call the tool by slug. Resyncing doesn't fix search. If the v3 tools API returns an empty list, use v3.1 or request the latest toolkit version. See [Custom MCP troubleshooting](https://docs.composio.dev/docs/extending-sessions/custom-mcp.md).
35 +
36 ## Identify the authentication boundary
37
38 ### Composio project or session 401
skills/composio/references/platform.md
+56 -1
@@ -141,14 +141,69 @@ If the application has its own connect UI, use session authorization and connect
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.