@devries-cameron20 / composio-1 / commits / 1be0fa142
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.

docs: keep session and MCP gateway documentation out of toolkit changes

Jeevesh Jain committed Nov 16, 2026 at 16:43 UTC 1be0fa1429155f4e10039f6b1245489a54f56cbc
14 files changed +48 -126
docs/agent/knowledge.md
+2 -2
@@ -16,9 +16,9 @@ A provider adapts Composio tools into the shape your AI framework expects. Compo
16
17 The userID scopes connected accounts and tool executions and isolates users from each other. Use a stable identifier such as your database UUID or primary key. Avoid email addresses (they change) and never use `default` in production, since that exposes one user's connections to others.
18
19 -## Direct tools (provider package) vs MCP transport (/docs/sessions-via-mcp)
19 +## Native tools vs MCP (/docs/sessions-via-mcp)
20
21 -By default a session gives your agent direct tools, called through a provider package (previously called native tools); this integrates with your framework and supports modifiers and custom tools. Creating a session with `{ mcp: true }` also exposes `session.mcp.url` and `session.mcp.headers` for any MCP-compatible client. MCP transport is more portable across clients, but modifiers and custom tools do not apply over the MCP surface.
21 +By default a session gives your agent tools it calls directly through a provider package; this integrates with your framework and supports modifiers and custom tools. Creating a session with `{ mcp: true }` also exposes `session.mcp.url` and `session.mcp.headers` for any MCP-compatible client. MCP is more portable across clients, but modifiers and custom tools do not apply over the MCP surface.
22
23 ## Apps: Composio Built vs Provider MCP toolkits (/docs/apps-and-toolkits)
24
docs/content/docs/apps-and-toolkits/composio-built-vs-provider-mcp.mdx
+1 -1
@@ -32,7 +32,7 @@ Compare each toolkit's details in the catalog.
32 3. **Tool coverage, checked in both directions.** A Provider MCP toolkit can expose capabilities only the product's own server offers, and it can also cover less of the product's API. Compare both tool lists before assuming the `_mcp` one is bigger or newer.
33 4. **Which account your users already have.** [Siblings never share a connection](/docs/apps-and-toolkits#sibling-toolkits-never-share-a-connection), so reuse an existing connection when that toolkit covers the task.
34
35 -Enable the toolkit your task needs. Enable both only when you need tools from both. [Configuring sessions](/docs/configuring-sessions#sibling-toolkits) has the enable and disable recipes.
35 +Enable the toolkit your task needs. Enable both only when you need tools from both. [Configuring sessions](/docs/configuring-sessions) has the enable and disable recipes.
36
37 <Callout type="info" title="Compare the task, not just the type">
38 Two toolkits can have the same type and serve different jobs or acting identities. Compare the tools and authentication even when both say Composio Built.
docs/content/docs/apps-and-toolkits/index.mdx
+1 -1
@@ -58,7 +58,7 @@ Connecting `notion` does _not_ connect `notion_mcp`, even for the same user. Eac
58 The same separation applies to session filters. `toolkits: ["notion"]` makes `notion` available without making `notion_mcp` available.
59
60 <Callout type="info" title="Check authentication for each toolkit">
61 -If both toolkits require authentication, each needs its own connection. A toolkit that declares no authentication does not require a sign-in. Enable the toolkits your task needs. See [Configuring sessions](/docs/configuring-sessions#sibling-toolkits) for the enable and disable examples.
61 +If both toolkits require authentication, each needs its own connection. A toolkit that declares no authentication does not require a sign-in. Enable the toolkits your task needs. See [Configuring sessions](/docs/configuring-sessions) for the enable and disable examples.
62 </Callout>
63
64 ## Find apps and toolkits in the dashboard
docs/content/docs/apps-and-toolkits/provider-mcps.mdx
+4 -12
@@ -1,6 +1,6 @@
1 ---
2 title: What are Provider MCPs
3 -description: Toolkits backed by a product's own hosted MCP server, how their slugs and tool names work, what auth they use, and where they differ from Composio's own MCP transports
3 +description: How Provider MCP toolkits use a product's hosted MCP server, with separate tool slugs and authentication
4 keywords: [provider mcp, provider mcps, notion_mcp, mcp toolkit, dcr oauth, mcp server, toolkit versions latest, custom mcp]
5 isNew: true
6 ---
@@ -36,17 +36,9 @@ DCR OAuth registers a client with the server during the connection flow. It does
36 A v3 tool listing can select a pinned version that predates the imported MCP tools. If `GET /api/v3/tools?toolkit_slug=notion_mcp` is empty, check the version before treating it as a sync failure. Add `toolkit_versions=latest`, or use v3.1, which defaults to the latest version. Session discovery does not use that v3 listing request. See [Toolkit versioning](/docs/tools-direct/toolkit-versioning).
37 </Callout>
38
39 -## Provider MCP vs MCP as a transport
40 -
41 -MCP shows up on both sides of Composio, and the two are independent. A Provider MCP toolkit is about where tools come from, with Composio acting as the MCP client. The MCP transports are about how your agent reaches Composio's tools.
42 -
43 -| You want to | Use | Read more |
44 -| --- | --- | --- |
45 -| Expose one user's session to an MCP-compatible client | The session MCP endpoint (`mcp: true`) | [Using sessions via MCP](/docs/sessions-via-mcp) |
46 -| Connect an existing MCP client to Composio without the SDK | Composio Connect | [Composio Connect](/docs/composio-connect) |
47 -| Use tools from a product's own hosted MCP server | A Provider MCP toolkit, like `notion_mcp` | This page |
48 -
49 -You can combine them, so you can enable `notion_mcp` in a session and serve it over the session MCP endpoint.
39 +<Callout type="info" title="Provider MCP toolkits and MCP gateway are separate">
40 +Provider MCP describes a toolkit in the catalog. Composio's MCP gateway is a separate product for connecting AI clients to Composio. This guide covers toolkit types and grouping.
41 +</Callout>
42
43 ## Your own server is Custom MCP, not Provider MCP
44
docs/content/docs/composio-connect.mdx
+11 -13
@@ -16,8 +16,6 @@ Composio Connect is an MCP server at `https://connect.composio.dev/mcp` that giv
16
17 Rather than exposing every app tool directly, Composio exposes **7 meta-tools** that let the agent discover what's available, authorize apps on demand, and execute tools across apps in parallel. The first time your agent needs an app, Composio generates an OAuth link you approve in your browser; after that the connection persists across sessions. See [Available MCP tools](#available-mcp-tools) for the full list.
18
19 -MCP here is the transport between your client and Composio; Provider MCP toolkits in the catalog, such as `notion_mcp`, are ordinary toolkits your agent can discover over this same connection. See [Apps and toolkits](/docs/apps-and-toolkits).
20 -
19 To get started, pick your client below.
20
21 <ConnectFlow>
@@ -457,15 +455,15 @@ Your agent will prompt you to connect apps when needed. If you want to connect a
455
456 ## Available MCP tools
457
460 -Composio Connect exposes 7 meta-tools that orchestrate access to all supported apps. Your agent uses these to discover, connect, and execute upstream tools. You don't need to call them directly.
458 +Composio Connect exposes 7 meta-tools that orchestrate access to all supported apps. Your agent uses these to discover, connect, and execute upstream tools — you don't need to call them directly.
459
462 -- **`COMPOSIO_SEARCH_TOOLS`**: Search the Composio catalog and return relevant tools for a user request, along with a suggested execution plan.
463 -- **`COMPOSIO_GET_TOOL_SCHEMAS`**: Fetch full input schemas for tool slugs returned by search.
464 -- **`COMPOSIO_MULTI_EXECUTE_TOOL`**: Execute one or more discovered tools in parallel across connected apps (up to 50 per call).
465 -- **`COMPOSIO_MANAGE_CONNECTIONS`**: Create, list, rename, or remove OAuth connections to upstream apps.
466 -- **`COMPOSIO_WAIT_FOR_CONNECTIONS`**: Wait for a user to complete an OAuth flow before the agent continues.
467 -- **`COMPOSIO_REMOTE_WORKBENCH`**: Run Python in a remote sandbox for bulk operations or processing large tool responses.
468 -- **`COMPOSIO_REMOTE_BASH_TOOL`**: Run bash in a remote sandbox for file processing and large data handling.
460 +- **`COMPOSIO_SEARCH_TOOLS`** — Search the Composio catalog and return relevant tools for a user request, along with a suggested execution plan.
461 +- **`COMPOSIO_GET_TOOL_SCHEMAS`** — Fetch full input schemas for tool slugs returned by search.
462 +- **`COMPOSIO_MULTI_EXECUTE_TOOL`** — Execute one or more discovered tools in parallel across connected apps (up to 50 per call).
463 +- **`COMPOSIO_MANAGE_CONNECTIONS`** — Create, list, rename, or remove OAuth connections to upstream apps.
464 +- **`COMPOSIO_WAIT_FOR_CONNECTIONS`** — Wait for a user to complete an OAuth flow before the agent continues.
465 +- **`COMPOSIO_REMOTE_WORKBENCH`** — Run Python in a remote sandbox for bulk operations or processing large tool responses.
466 +- **`COMPOSIO_REMOTE_BASH_TOOL`** — Run bash in a remote sandbox for file processing and large data handling.
467
468 ## Troubleshooting
469
@@ -474,12 +472,12 @@ Composio Connect exposes 7 meta-tools that orchestrate access to all supported a
472 1. Confirm the MCP server is connected. In Claude Desktop, go to **Settings > Connectors** and check that Composio shows a `CUSTOM` badge. In Claude Code, run `/mcp` and confirm Composio is enabled.
473 2. Clear the connector cache. In Claude Desktop: click the **⋮** next to Composio and select **Clear cache**.
474 3. If the issue persists, disconnect and re-add the connector:
477 - - **Claude Desktop**: click **⋮ > Disconnect**, then **Remove**. Re-add via **Add custom connector**.
478 - - **Claude Code**: re-run the setup command from the Claude Code section above.
475 + - **Claude Desktop** — click **⋮ > Disconnect**, then **Remove**. Re-add via **Add custom connector**.
476 + - **Claude Code** — re-run the setup command from the Claude Code section above.
477
478 ### The OAuth link expired or didn't open
479
482 -OAuth links are short-lived. If the browser window doesn't open or the link has expired, ask your agent to retry the action. Composio will generate a fresh link.
480 +OAuth links are short-lived. If the browser window doesn't open or the link has expired, ask your agent to retry the action — Composio will generate a fresh link.
481
482 ### An app action is failing with an auth error
483
docs/content/docs/configuring-sessions.mdx
-56
@@ -207,62 +207,6 @@ Requires `@composio/core` ≥ `0.19.1` (TypeScript) or `composio` ≥ `0.22.1` (
207
208 The session API rejects unknown root keys with a `400` before it creates anything. A typo such as a singular `toolkit` fails the request instead of silently creating an unrestricted session.
209
210 -## Sibling toolkits
211 -
212 -When a product has more than one toolkit, each has its own slug, and enabling one never enables the other. Enable `["notion_mcp"]` to use only Notion's Provider MCP toolkit, or disable one sibling to exclude it while keeping other toolkits discoverable. You can't pass an App: the `toolkits` lists take exact toolkit slugs only. See [Apps vs toolkits](/docs/apps-and-toolkits) for what the siblings are, and [Composio Built vs Provider MCPs](/docs/apps-and-toolkits/composio-built-vs-provider-mcp) for picking one.
213 -
214 -<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
215 -<Tab value="Python">
216 -```python
217 -from composio import Composio
218 -
219 -composio = Composio()
220 -# Only the Provider MCP toolkit
221 -session = composio.sessions.create(
222 - user_id="user_123",
223 - toolkits=["notion_mcp"]
224 -)
225 -
226 -# Keep other toolkits discoverable, but exclude notion_mcp
227 -session = composio.sessions.create(
228 - user_id="user_123",
229 - toolkits={"disable": ["notion_mcp"]}
230 -)
231 -```
232 -</Tab>
233 -<Tab value="TypeScript">
234 -```typescript
235 -import { Composio } from '@composio/core';
236 -const composio = new Composio({ apiKey: 'your_api_key' });
237 -// ---cut---
238 -// Only the Provider MCP toolkit
239 -const session = await composio.create("user_123", {
240 - toolkits: ["notion_mcp"],
241 -});
242 -
243 -// Keep other toolkits discoverable, but exclude notion_mcp
244 -const session2 = await composio.create("user_123", {
245 - toolkits: { disable: ["notion_mcp"] },
246 -});
247 -```
248 -</Tab>
249 -<Tab value="API">
250 -```bash
251 -# Only the Provider MCP toolkit
252 -curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
253 - -H "x-api-key: $COMPOSIO_API_KEY" \
254 - -H "Content-Type: application/json" \
255 - -d '{"user_id": "user_123", "toolkits": {"enable": ["notion_mcp"]}}'
256 -
257 -# Keep other toolkits discoverable, but exclude notion_mcp
258 -curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
259 - -H "x-api-key: $COMPOSIO_API_KEY" \
260 - -H "Content-Type: application/json" \
261 - -d '{"user_id": "user_123", "toolkits": {"disable": ["notion_mcp"]}}'
262 -```
263 -</Tab>
264 -</Tabs>
265 -
210 ## Direct tools preset
211
212 The direct tools preset preloads every tool allowed by session filters into the session's tool list and disables session meta tools by default. Use it for specialized agents with a narrow tool set that don't need dynamic tool discovery, in-chat auth, or workbench helpers.
docs/content/docs/extending-sessions/custom-mcp.mdx
-4
@@ -13,10 +13,6 @@ Custom MCP is experimental. The APIs may change.
13
14 This is different from [Local Tools and Toolkits](/docs/extending-sessions/local-tools-and-toolkits), which run inside your app. A Custom MCP server runs on its own public HTTPS URL.
15
16 -<Callout type="info" title="Custom MCP vs Provider MCP">
17 -A Custom MCP toolkit registers a remote server for your project or one user and has a `CUSTOM_*` slug. A Provider MCP toolkit, such as `notion_mcp`, connects to a product's hosted MCP server and is part of the catalog. See [Apps and toolkits](/docs/apps-and-toolkits).
18 -</Callout>
19 -
16 ## How it works
17
18 1. **Get** a remote MCP server at a public HTTPS URL: your own, or an existing one.
docs/content/docs/how-composio-works.mdx
-2
@@ -73,8 +73,6 @@ architecture-beta
73
74 Below we're going to explain each of the concepts that come with a session.
75
76 -Some products have multiple toolkits. The catalog can group them into an **App** for comparison, such as `notion` and `notion_mcp`. Each toolkit keeps its own tools and connections. Configure sessions with exact toolkit slugs. See [Apps vs toolkits](/docs/apps-and-toolkits).
77 -
76 ## Users
77
78 A user is an identifier from your app. Composio stores connections under that ID, so tools run with the right account and stay isolated from other users. Use a stable identifier like your database ID, never one that can change.
docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx
+3 -3
@@ -241,12 +241,12 @@ span many toolkits without bloating context.
241
242 ## Beyond the MCP URL
243
244 -A session isn't only an MCP endpoint: it's also a normal SDK object, which is handy for non-agent
244 +A session isn't only an MCP endpoint — it's also a normal SDK object, which is handy for non-agent
245 code paths.
246
247 -### Direct tools for your framework
247 +### Native tools for your framework
248
249 -`session.tools()` returns provider-wrapped direct tools for OpenAI, Anthropic, LangChain, the Vercel
249 +`session.tools()` returns provider-wrapped native tools for OpenAI, Anthropic, LangChain, the Vercel
250 AI SDK, and others, so you skip manual schema wiring. With the direct-tools preset it returns your
251 exact fixed tool set; by default it returns the meta-tools that drive runtime discovery.
252
docs/content/docs/sessions-via-mcp.mdx
-4
@@ -16,10 +16,6 @@ If you use Codex or Claude Code and did not explicitly choose MCP, install the n
16 Want to bring tools from your own remote MCP server into Composio instead? See [Custom MCP](/docs/extending-sessions/custom-mcp).
17 </Callout>
18
19 -<Callout type="info">
20 -MCP on this page is the transport that exposes a session to a client. It is independent of Provider MCP toolkits such as `notion_mcp`, which are catalog toolkits you can use over any transport. See [Apps and toolkits](/docs/apps-and-toolkits).
21 -</Callout>
22 -
19 ## The MCP endpoint
20
21 If you use a scoped project API key, enable **Session management** to create and configure sessions and **Session tool execution** for session-linked MCP access. See [API key permissions](/reference/authenticating-to-composio/project-api-key-permissions) for access levels and routes.
docs/content/reference/glossary.mdx
+21 -21
@@ -55,10 +55,6 @@ Your own remote MCP server registered into your project as a toolkit with a `CUS
55 OAuth Dynamic Client Registration, the auth scheme many Provider MCP toolkits use. The client registers itself with the product's MCP server automatically, so your user just approves access and there is no OAuth app to register.
56 </GlossaryTerm>
57
58 -<GlossaryTerm name="Direct tools (provider package)">
59 -Tools you access through provider packages with `session.tools()` and call directly, rather than over MCP. Both paths give the agent the same capabilities, but tools called directly integrate with your AI framework and support modifiers and local tools. Previously called native tools.
60 -</GlossaryTerm>
61 -
58 <GlossaryTerm name="In-Chat Authentication">
59 A flow in which the agent handles authentication itself by calling `COMPOSIO_MANAGE_CONNECTIONS` to generate a Connect Link and send it to the user in the conversation. See [In-chat authentication](/docs/authentication#in-chat-authentication).
60 </GlossaryTerm>
@@ -67,14 +63,14 @@ A flow in which the agent handles authentication itself by calling `COMPOSIO_MAN
63 A tool you define yourself that runs in your application process alongside Composio's built-in tools. Previously called a custom tool. Add experimental local tools and local toolkits through [Local tools and toolkits](/docs/extending-sessions/local-tools-and-toolkits).
64 </GlossaryTerm>
65
70 -<GlossaryTerm name="Manual Authentication">
71 -Authenticating users from your own code with `session.authorize()` or `connectedAccounts.link()`, rather than letting the agent handle it through in-chat authentication. See [Manual authentication](/docs/authentication/manually-authenticating).
72 -</GlossaryTerm>
73 -
66 <GlossaryTerm name="MCP (Model Context Protocol)">
67 An open protocol for connecting AI models to external tools. Create a session with `mcp: true` to expose `session.mcp.url` and `session.mcp.headers`, an MCP-compatible endpoint any MCP client can connect to. See [Using sessions via MCP](/docs/sessions-via-mcp).
68 </GlossaryTerm>
69
70 +<GlossaryTerm name="Manual Authentication">
71 +Authenticating users from your own code with `session.authorize()` or `connectedAccounts.link()`, rather than letting the agent handle it through in-chat authentication. See [Manual authentication](/docs/authentication/manually-authenticating).
72 +</GlossaryTerm>
73 +
74 <GlossaryTerm name="Meta Tools">
75 A set of tools included in every session: `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_GET_TOOL_SCHEMAS`, `COMPOSIO_MANAGE_CONNECTIONS`, `COMPOSIO_MULTI_EXECUTE_TOOL`, `COMPOSIO_REMOTE_WORKBENCH`, and `COMPOSIO_REMOTE_BASH_TOOL`. They let the agent discover tools, manage auth, execute in parallel, and run code without loading hundreds of tool definitions upfront. See [Meta Tools Reference](/toolkits/meta-tools).
76 </GlossaryTerm>
@@ -83,6 +79,10 @@ A set of tools included in every session: `COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_GET
79 Middleware that transforms tool behavior. [Schema modifiers](/docs/tools-direct/modify-tool-behavior/schema-modifiers) change a tool's schema before the agent sees it, [before-execution modifiers](/docs/tools-direct/modify-tool-behavior/before-execution-modifiers) change arguments before a tool runs, and [after-execution modifiers](/docs/tools-direct/modify-tool-behavior/after-execution-modifiers) transform the result. In Python, [`@before_file_upload`](/docs/tools-direct/modify-tool-behavior/before-execution-modifiers#before-file-upload-python) intercepts local paths for `file_uploadable` parameters before read and upload.
80 </GlossaryTerm>
81
82 +<GlossaryTerm name="Native Tools">
83 +Tools you access through provider packages with `session.tools()` and call directly, rather than over MCP. Both paths give the agent the same capabilities, but tools called directly integrate with your AI framework and support modifiers and local tools.
84 +</GlossaryTerm>
85 +
86 <GlossaryTerm name="Organization">
87 The top-level Composio account entity. It contains team members and projects.
88 </GlossaryTerm>
@@ -95,6 +95,10 @@ A key (`x-org-api-key`) for organization-level operations such as creating and m
95 An isolated environment within an organization that scopes API keys, connected accounts, auth configs, and webhooks. Resources in one project are inaccessible from another. IDs are prefixed `proj_`. See [Projects](/reference/api-reference/projects).
96 </GlossaryTerm>
97
98 +<GlossaryTerm name="Proxy Execute">
99 +Making authenticated HTTP requests through a toolkit's connected account without a predefined tool. Use it for API endpoints Composio has no built-in tool for.
100 +</GlossaryTerm>
101 +
102 <GlossaryTerm name="Provider">
103 An adapter package that transforms Composio tools into the format an AI framework expects (OpenAI, Anthropic, LangChain, Vercel AI SDK, and others). See [Providers](/docs/providers).
104 </GlossaryTerm>
@@ -103,16 +107,8 @@ An adapter package that transforms Composio tools into the format an AI framewor
107 A toolkit that connects to the product's own hosted MCP server, maintained by that product. Many slugs end in `_mcp`, such as `notion_mcp`. Check the catalog type and the toolkit's authentication methods. Not to be confused with a provider, which is an AI-framework adapter. See [Apps and toolkits](/docs/apps-and-toolkits).
108 </GlossaryTerm>
109
106 -<GlossaryTerm name="Proxy Execute">
107 -Making authenticated HTTP requests through a toolkit's connected account without a predefined tool. Use it for API endpoints Composio has no built-in tool for.
108 -</GlossaryTerm>
109 -
110 -<GlossaryTerm name="Sandbox">
111 -A persistent Python environment (previously called the workbench) exposed through the `COMPOSIO_REMOTE_WORKBENCH` meta tool. Its state persists across calls within a session, which makes it useful for bulk operations, data transformations, and processing large tool responses. Configure it with the `sandbox` session key; `workbench` still works as an alias. See [Sandbox](/docs/sandbox/remote).
112 -</GlossaryTerm>
113 -
110 <GlossaryTerm name="Session">
115 -The runtime context returned by `composio.create(userId)`. It ties together a userID, the available toolkits, an auth config, and connected accounts, and it exposes `tools()`, `authorize()`, and `toolkits()` (plus `mcp.url` when created with `mcp: true`). See [What is a session?](/docs/how-composio-works).
111 +An ephemeral, immutable configuration object returned by `composio.create(userId)`. It ties together a userID, the available toolkits, an auth config, and connected accounts, and it exposes `tools()`, `authorize()`, and `toolkits()` (plus `mcp.url` when created with `mcp: true`). See [What is a session?](/docs/how-composio-works).
112 </GlossaryTerm>
113
114 <GlossaryTerm name="Session ID">
@@ -147,10 +143,6 @@ A source that sends structured payloads to your application when something happe
143 A specific, active trigger scoped to a user's connected account.
144 </GlossaryTerm>
145
150 -<GlossaryTerm name="userID">
151 -An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between userIDs. See [What is a session?](/docs/how-composio-works).
152 -</GlossaryTerm>
153 -
146 <GlossaryTerm name="Webhook Endpoint">
147 The ingress URL Composio issues per OAuth app for webhook triggers, plus the signing secret used to verify each inbound request. Composio configures it for you in most cases. When a trigger type's `requires_webhook_endpoint_setup` flag is `true`, you configure it yourself once per OAuth app through the [Webhook Endpoints API](/reference/api-reference/webhook-endpoints). See [Custom OAuth webhooks](/docs/setting-up-triggers/custom-oauth-webhooks).
148 </GlossaryTerm>
@@ -159,8 +151,16 @@ The ingress URL Composio issues per OAuth app for webhook triggers, plus the sig
151 The URL Composio delivers signed events to in your application. There is one per project, configured through the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhook-subscriptions). See [Subscribing to events](/docs/setting-up-triggers/subscribing-to-events).
152 </GlossaryTerm>
153
154 +<GlossaryTerm name="userID">
155 +An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between userIDs. See [What is a session?](/docs/how-composio-works).
156 +</GlossaryTerm>
157 +
158 <GlossaryTerm name="White-Labeling">
159 Customizing the auth experience so users see your brand during the OAuth flow. You provide your own OAuth credentials, redirect URIs, and branding. See [White-labeling authentication](/docs/authentication/white-labeling-authentication).
160 </GlossaryTerm>
161
162 +<GlossaryTerm name="Sandbox">
163 +A persistent Python environment (previously called the workbench) exposed through the `COMPOSIO_REMOTE_WORKBENCH` meta tool. Its state persists across calls within a session, which makes it useful for bulk operations, data transformations, and processing large tool responses. Configure it with the `sandbox` session key; `workbench` still works as an alias. See [Sandbox](/docs/sandbox/remote).
164 +</GlossaryTerm>
165 +
166 </Glossary>
docs/decisions/apps-and-toolkits.md
+2 -2
@@ -16,9 +16,9 @@ An **App** groups related catalog toolkits for comparison. Each toolkit retains
16
17 ## Documentation scope
18
19 -The three guides cover App grouping, Provider MCP behavior, and choosing a toolkit. Session configuration, the glossary, agent instructions, LLM guardrails, and the Composio skill use the same terminology. Session MCP transport remains separate from Provider MCP toolkits.
19 +The three guides cover App grouping, Provider MCP behavior, and choosing a toolkit. The glossary, toolkit guidance for agents, and the Composio skill use the same catalog terminology. MCP gateway is a separate product. Session and gateway docs, their Native Tools terminology, and their Markdown rendering remain unchanged.
20
21 -The replacement for PR #4336 carries the content onto the current `next` branch. It preserves the newer Custom MCP scope and session configuration docs and moves the agent guidance into `docs/agent/instructions/context.ts`.
21 +The replacement for PR #4336 carries the content onto the current `next` branch. It adds toolkit guidance to the current `docs/agent/instructions/context.ts`.
22
23 The September staging screenshots are omitted because they contain personal workspace details, old counts, and grouping examples that no longer match the backend-owned contract. Fresh demo-workspace screenshots can be added separately.
24
docs/lib/llm-guardrails/session.ts
+2 -4
@@ -28,11 +28,11 @@ export const SESSION_GUARDRAILS = `
28
29 ## 1. Recommended Integration: Sessions
30
31 -For agent tool delivery, Composio supports **direct tools** (through a provider package) and **MCP** (no provider package needed).
31 +For agent tool delivery, Composio supports **Native Tools** (with a provider package) and **MCP** (no provider package needed).
32
33 For application-owned tools or deterministic backend code, use [managed authentication with Proxy Execute](/docs/authentication/managed-auth-for-custom-tools). A session can provide a user-scoped runtime context without an LLM or MCP. Composio authenticates provider requests server-side; connected-account reads redact credentials and aren't a supported token-export workflow.
34
35 -### Direct tools (provider package)
35 +### Native Tools
36
37 #### Python
38
@@ -91,8 +91,6 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie
91
92 ## 2. Integration Notes
93
94 -- App grouping does not combine toolkit connections or tools. Configure exact toolkit slugs, such as \`notion\` or \`notion_mcp\`, and use the one the request names.
95 -
94 - \`composio.create(user_id)\` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; \`user_id\` goes to \`composio.create()\` — individual tool calls in session mode don't take one.
95 - Execute session tool calls through the session, never through a user ID: either \`session.execute(tool_slug, arguments=...)\` / \`session.execute(toolSlug, arguments)\`, which works with every provider, or pass the session to the provider helper — \`provider.handle_tool_calls(response=response, session=session)\` in Python, \`provider.handleToolCalls(session, response)\` in TypeScript. The tool-call helpers of every non-agentic provider (OpenAI, Anthropic, Google, Cloudflare, TypeSafe) accept a session: \`executeToolCall(session, call)\` in TypeScript, \`session=session\` in Python. Agentic providers execute session tools on their own. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with \`"can only be called inside a tool-router session"\`.
96 - Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits.
docs/lib/source.ts
+1 -1
@@ -442,7 +442,7 @@ export function mdxToCleanMarkdown(content: string, url?: string): string {
442 result = result.replace(/<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n## $1\n');
443 result = result.replace(/<\/FrameworkOption>/g, '');
444
445 - const tabLabelMap: Record<string, string> = { native: 'Direct tools', mcp: 'MCP' };
445 + const tabLabelMap: Record<string, string> = { native: 'Native Tools', mcp: 'MCP' };
446 result = result.replace(
447 /<IntegrationTabs[\s\S]*?tabs=\{\[([\s\S]*?)\]\}[\s\S]*?>/g,
448 (_, tabsContent: string) => {