Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxindex 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.mdxindex 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. YoYou 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 toolkitsRestrict 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>### mcpGet 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">```pythondiff --git a/docs/content/docs/glossary.mdx b/docs/content/docs/glossary.mdxindex 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.mdxindex 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 accountsUse `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.mdxindex 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">```pythondiff --git a/docs/content/docs/troubleshooting/index.mdx b/docs/content/docs/troubleshooting/index.mdxindex 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>