Skip to content

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)

github-actions[bot]4312e0cae396
diff --git a/docs/content/docs/common-faq.mdx b/docs/content/docs/common-faq.mdx
index 6bfa8e55f..134a9dbf2 100644
--- a/docs/content/docs/common-faq.mdx
+++ b/docs/content/docs/common-faq.mdx
@@ -39,7 +39,9 @@ See [Native Tools vs MCP](/docs/native-tools-vs-mcp) for a full comparison.
</Accordion>
<Accordion title="When should I create a new session?">
-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).
+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.
+
+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).
</Accordion>
</Accordions>
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index 3dce417b7..c3c53d6b9 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -26,6 +26,8 @@ By default, a session has access to **all toolkits** in the Composio catalog. Yo
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).
+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.
+
## Enabling toolkits
Restrict the session to specific toolkits:
@@ -494,12 +496,75 @@ const session = await composio.create("user_123", {
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.
-## Session methods
+## Session lifecycle and methods
+
+### use()
+
+Reuse an existing session by ID. This keeps tool, auth, MCP, and workbench context available across multi-turn requests.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# First request
+session = composio.create(user_id="user_123")
+session_id = session.session_id
+
+# Later request
+session = composio.use(session_id)
+tools = session.tools()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// First request
+const session = await composio.create("user_123");
+const sessionId = session.sessionId;
+
+// Later request
+const reusedSession = await composio.use(sessionId);
+const tools = await reusedSession.tools();
+```
+</Tab>
+</Tabs>
+
+### update()
+
+Patch an existing session without creating a new session ID. Only the fields you pass are changed.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session.update(
+ toolkits=["gmail", "slack"],
+ auth_configs={"gmail": "ac_new_config"},
+ connected_accounts={"slack": ["ca_work_slack"]},
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.use("session_id");
+// ---cut---
+await session.update({
+ toolkits: ["gmail", "slack"],
+ authConfigs: { gmail: "ac_new_config" },
+ connectedAccounts: { slack: ["ca_work_slack"] },
+});
+```
+</Tab>
+</Tabs>
### mcp
Get the MCP server URL to use with any MCP-compatible client.
+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`.
+
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
diff --git a/docs/content/docs/glossary.mdx b/docs/content/docs/glossary.mdx
index 11bf3864d..bf3191c5c 100644
--- a/docs/content/docs/glossary.mdx
+++ b/docs/content/docs/glossary.mdx
@@ -88,11 +88,11 @@ An adapter package that transforms Composio tools into the format expected by an
</GlossaryTerm>
<GlossaryTerm name="Session">
-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).
+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).
</GlossaryTerm>
<GlossaryTerm name="Session ID">
-Unique identifier for a session. Used internally by meta tools to share context across calls within the same session.
+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.
</GlossaryTerm>
<GlossaryTerm name="Tool">
diff --git a/docs/content/docs/managing-multiple-connected-accounts.mdx b/docs/content/docs/managing-multiple-connected-accounts.mdx
index 03edb9017..0d5a621e6 100644
--- a/docs/content/docs/managing-multiple-connected-accounts.mdx
+++ b/docs/content/docs/managing-multiple-connected-accounts.mdx
@@ -214,6 +214,10 @@ const session = await composio.create("user_123", {
</Tab>
</Tabs>
+<Callout type="info">
+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.
+</Callout>
+
## Viewing session's active accounts
Use `session.toolkits()` to see which accounts are currently active:
diff --git a/docs/content/docs/single-toolkit-mcp.mdx b/docs/content/docs/single-toolkit-mcp.mdx
index f9110009a..613a3a4da 100644
--- a/docs/content/docs/single-toolkit-mcp.mdx
+++ b/docs/content/docs/single-toolkit-mcp.mdx
@@ -104,6 +104,10 @@ console.log(`Server created: ${server.id}`);
Users must authenticate with the toolkits configured in your MCP server first. See [authentication](/docs/authentication) for details.
</Callout>
+ <Callout type="info">
+ 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.
+ </Callout>
+
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
```python
diff --git a/docs/content/docs/troubleshooting/index.mdx b/docs/content/docs/troubleshooting/index.mdx
index e1f6d2726..6d7309989 100644
--- a/docs/content/docs/troubleshooting/index.mdx
+++ b/docs/content/docs/troubleshooting/index.mdx
@@ -24,7 +24,7 @@ See [Troubleshooting authentication](/docs/troubleshooting/authentication#report
</Accordion>
<Accordion title="How do I find my MCP server ID?">
-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.
+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`.
See [Troubleshooting MCP](/docs/troubleshooting/mcp#reporting-mcp-issues) for a visual guide.
</Accordion>