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: update documentation for new changelog entries (#3458)
## Summary Automated documentation updates triggered by new changelog entries merged to next. Generated by Codex via GitHub Actions. Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com> Co-authored-by: jkomyno <alberto@composio.dev> Co-authored-by: Alberto Schiabel <jkomyno@users.noreply.github.com>
github-actions[bot] committed
Jun 25, 2026 at 03:36 UTC
4312e0cae3969968bcb731daebb02adf9acb8b46
6 files changed
+80
-5
docs/content/docs/common-faq.mdx
+3
-1
@@ -39,7 +39,9 @@ See [Native Tools vs MCP](/docs/native-tools-vs-mcp) for a full comparison.
39
</Accordion>
40
41
<Accordion title="When should I create a new session?">
42
-Create a new session when the config changes: different toolkits, different auth config, or a different connected account. You don't need to store or manage session IDs. Just call `create()` each time. See [What is a session?](/docs/how-composio-works).
42
+Create a new session when you want a fresh task context, a different user, or a fundamentally different setup. Every `create()` call returns a new session ID, even if you pass the same config.
43
+
44
+For multi-turn conversations, store the session ID and call `composio.use(session_id)` / `composio.use(sessionId)` on later requests. If the same conversation needs different toolkits, auth configs, or connected accounts, update the existing session with `session.update()` instead of creating a new one. See [What is a session?](/docs/how-composio-works).
45
</Accordion>
46
47
</Accordions>
docs/content/docs/configuring-sessions.mdx
+66
-1
@@ -26,6 +26,8 @@ By default, a session has access to **all toolkits** in the Composio catalog. Yo
26
27
You can also attach local experimental custom tools and custom toolkits that run in-process alongside Composio tools. See [Custom tools and toolkits](/docs/toolkits/custom-tools-and-toolkits).
28
29
+Every `create()` call returns a new session ID. For multi-turn conversations, store the session ID and reuse it with `composio.use()` instead of calling `create()` for each turn.
30
+
31
## Enabling toolkits
32
33
Restrict the session to specific toolkits:
@@ -494,12 +496,75 @@ const session = await composio.create("user_123", {
496
497
Changing `sandbox_size` on an existing session recreates the sandbox on next access. The sandbox's in-memory filesystem state is lost, but the persistent `/mnt/files/` mount survives the restart.
498
497
-## Session methods
499
+## Session lifecycle and methods
500
+
501
+### use()
502
+
503
+Reuse an existing session by ID. This keeps tool, auth, MCP, and workbench context available across multi-turn requests.
504
+
505
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
506
+<Tab value="Python">
507
+```python
508
+# First request
509
+session = composio.create(user_id="user_123")
510
+session_id = session.session_id
511
+
512
+# Later request
513
+session = composio.use(session_id)
514
+tools = session.tools()
515
+```
516
+</Tab>
517
+<Tab value="TypeScript">
518
+```typescript
519
+import { Composio } from '@composio/core';
520
+const composio = new Composio({ apiKey: 'your_api_key' });
521
+// ---cut---
522
+// First request
523
+const session = await composio.create("user_123");
524
+const sessionId = session.sessionId;
525
+
526
+// Later request
527
+const reusedSession = await composio.use(sessionId);
528
+const tools = await reusedSession.tools();
529
+```
530
+</Tab>
531
+</Tabs>
532
+
533
+### update()
534
+
535
+Patch an existing session without creating a new session ID. Only the fields you pass are changed.
536
+
537
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
538
+<Tab value="Python">
539
+```python
540
+session.update(
541
+ toolkits=["gmail", "slack"],
542
+ auth_configs={"gmail": "ac_new_config"},
543
+ connected_accounts={"slack": ["ca_work_slack"]},
544
+)
545
+```
546
+</Tab>
547
+<Tab value="TypeScript">
548
+```typescript
549
+import { Composio } from '@composio/core';
550
+const composio = new Composio({ apiKey: 'your_api_key' });
551
+const session = await composio.use("session_id");
552
+// ---cut---
553
+await session.update({
554
+ toolkits: ["gmail", "slack"],
555
+ authConfigs: { gmail: "ac_new_config" },
556
+ connectedAccounts: { slack: ["ca_work_slack"] },
557
+});
558
+```
559
+</Tab>
560
+</Tabs>
561
562
### mcp
563
564
Get the MCP server URL to use with any MCP-compatible client.
565
566
+Use the SDK-generated `session.mcp.url` as-is. MCP URLs include the session's user context; if you construct a single-toolkit MCP URL manually, include either `user_id` or `connected_account_id`.
567
+
568
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
569
<Tab value="Python">
570
```python
docs/content/docs/glossary.mdx
+2
-2
@@ -88,11 +88,11 @@ An adapter package that transforms Composio tools into the format expected by an
88
</GlossaryTerm>
89
90
<GlossaryTerm name="Session">
91
-An ephemeral configuration object from `composio.create(userId)`. Ties together a user ID, available toolkits, auth config, and connected accounts. Immutable. Exposes `tools()`, `mcp.url`, `authorize()`, and `toolkits()`. See [What is a session?](/docs/how-composio-works).
91
+A runtime context from `composio.create(userId)`. Ties together a user ID, available toolkits, auth configs, connected accounts, MCP state, and workbench state. Store its session ID and reuse it with `composio.use()` for multi-turn conversations, or patch its config with `session.update()`. Exposes `tools()`, `mcp.url`, `authorize()`, and `toolkits()`. See [What is a session?](/docs/how-composio-works).
92
</GlossaryTerm>
93
94
<GlossaryTerm name="Session ID">
95
-Unique identifier for a session. Used internally by meta tools to share context across calls within the same session.
95
+Unique identifier for a session. Store it for multi-turn conversations and pass it to `composio.use()` to rehydrate the same session context across requests.
96
</GlossaryTerm>
97
98
<GlossaryTerm name="Tool">
docs/content/docs/managing-multiple-connected-accounts.mdx
+4
@@ -214,6 +214,10 @@ const session = await composio.create("user_123", {
214
</Tab>
215
</Tabs>
216
217
+<Callout type="info">
218
+Arrays are the preferred format for `connected_accounts` / `connectedAccounts`. A single connected account ID string is still accepted for backwards compatibility and is treated as a one-item array.
219
+</Callout>
220
+
221
## Viewing session's active accounts
222
223
Use `session.toolkits()` to see which accounts are currently active:
docs/content/docs/single-toolkit-mcp.mdx
+4
@@ -104,6 +104,10 @@ console.log(`Server created: ${server.id}`);
104
Users must authenticate with the toolkits configured in your MCP server first. See [authentication](/docs/authentication) for details.
105
</Callout>
106
107
+ <Callout type="info">
108
+ Generated MCP URLs are scoped to a user. If you build an MCP URL yourself, include either `user_id` or `connected_account_id` as a query parameter.
109
+ </Callout>
110
+
111
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
112
<Tab value="Python">
113
```python
docs/content/docs/troubleshooting/index.mdx
+1
-1
@@ -24,7 +24,7 @@ See [Troubleshooting authentication](/docs/troubleshooting/authentication#report
24
</Accordion>
25
26
<Accordion title="How do I find my MCP server ID?">
27
-Your MCP server ID is the UUID in the server URL (e.g., `https://backend.composio.dev/v3/mcp/<UUID>/mcp`). You can also find it in the [dashboard](https://dashboard.composio.dev) under your MCP server's detail page.
27
+Your MCP server ID is the UUID in the server URL (e.g., `https://backend.composio.dev/v3/mcp/<UUID>?user_id=user_123`). You can also find it in the [dashboard](https://dashboard.composio.dev) under your MCP server's detail page. MCP URLs must include either `user_id` or `connected_account_id`.
28
29
See [Troubleshooting MCP](/docs/troubleshooting/mcp#reporting-mcp-issues) for a visual guide.
30
</Accordion>