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: add session methods, delete temporary file
- Add session methods section to users-and-sessions.mdx - Add detailed session methods to configuring-sessions.mdx - Move Configuring Sessions card to end of page - Delete users-and-sessions-temporary.mdx - Fix broken guides/ links Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 24, 2026 at 00:52 UTC
be5f7183c78c2533580f73a0286b15c28cd853a1
4 files changed
+154
-289
docs/content/docs/configuring-sessions.mdx
+112
-1
@@ -116,7 +116,7 @@ const session = await composio.create("user_123", {
116
</Tab>
117
</Tabs>
118
119
-See [White-labeling authentication](/docs/guides/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/guides/using-custom-auth-configuration) for toolkits that require your own credentials.
119
+See [White-labeling authentication](/docs/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/using-custom-auth-configuration) for toolkits that require your own credentials.
120
121
## Account selection
122
@@ -160,3 +160,114 @@ When executing a tool, the connected account is selected in this order:
160
5. Error if no Composio managed auth scheme exists for the toolkit
161
162
If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
163
+
164
+## Session methods
165
+
166
+### mcp
167
+
168
+Get the MCP server URL to use with any MCP-compatible client.
169
+
170
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
171
+<Tab value="Python">
172
+```python
173
+mcp_url = session.mcp.url
174
+```
175
+</Tab>
176
+<Tab value="TypeScript">
177
+```typescript
178
+import { Composio } from '@composio/core';
179
+const composio = new Composio({ apiKey: 'your_api_key' });
180
+const session = await composio.create("user_123");
181
+// ---cut---
182
+const { mcp } = session;
183
+console.log(mcp.url);
184
+```
185
+</Tab>
186
+</Tabs>
187
+
188
+For framework examples, see provider-specific documentation like [OpenAI Agents](/docs/providers/openai-agents) or [Vercel AI SDK](/docs/providers/vercel).
189
+
190
+### tools()
191
+
192
+Get native tools from the session for use with AI frameworks.
193
+
194
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
195
+<Tab value="Python">
196
+```python
197
+tools = session.tools()
198
+```
199
+</Tab>
200
+<Tab value="TypeScript">
201
+```typescript
202
+import { Composio } from '@composio/core';
203
+const composio = new Composio({ apiKey: 'your_api_key' });
204
+const session = await composio.create("user_123");
205
+// ---cut---
206
+const tools = await session.tools();
207
+```
208
+</Tab>
209
+</Tabs>
210
+
211
+### authorize()
212
+
213
+Manually authenticate a user to a toolkit outside of the chat flow.
214
+
215
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
216
+<Tab value="Python">
217
+```python
218
+connection_request = session.authorize("github")
219
+
220
+print(connection_request.redirect_url)
221
+
222
+connected_account = connection_request.wait_for_connection()
223
+```
224
+</Tab>
225
+<Tab value="TypeScript">
226
+```typescript
227
+import { Composio } from '@composio/core';
228
+const composio = new Composio({ apiKey: 'your_api_key' });
229
+const session = await composio.create("user_123");
230
+// ---cut---
231
+const connectionRequest = await session.authorize("github", {
232
+ callbackUrl: "https://myapp.com/callback",
233
+});
234
+
235
+console.log(connectionRequest.redirectUrl);
236
+
237
+const connectedAccount = await connectionRequest.waitForConnection();
238
+```
239
+</Tab>
240
+</Tabs>
241
+
242
+For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).
243
+
244
+### toolkits()
245
+
246
+List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
247
+
248
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
249
+<Tab value="Python">
250
+```python
251
+toolkits = session.toolkits()
252
+
253
+for toolkit in toolkits.items:
254
+ status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
255
+ print(f"{toolkit.name}: {status}")
256
+```
257
+</Tab>
258
+<Tab value="TypeScript">
259
+```typescript
260
+import { Composio } from '@composio/core';
261
+const composio = new Composio({ apiKey: 'your_api_key' });
262
+const session = await composio.create("user_123");
263
+// ---cut---
264
+const toolkits = await session.toolkits();
265
+
266
+toolkits.items.forEach((toolkit) => {
267
+ console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
268
+});
269
+```
270
+</Tab>
271
+</Tabs>
272
+
273
+Returns the first 20 toolkits by default.
docs/content/docs/meta.json
-1
@@ -6,7 +6,6 @@
6
"quickstart-tool-router",
7
"providers",
8
"---Core Concepts---",
9
- "users-and-sessions-temporary",
9
"users-and-sessions",
10
"authentication",
11
"tools-and-toolkits",
docs/content/docs/users-and-sessions-temporary.mdx
deleted
-286
@@ -1,286 +0,0 @@
1
----
2
-title: Users & Sessions Temporary
3
-description: Understand how Tool Router scopes tools and connections per user
4
-keywords: [session, user id, enable toolkits, disable toolkits]
5
----
6
-
7
-A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. See [User Management](/docs/user-management) for best practices.
8
-
9
-A **session** is an ephemeral configuration that combines:
10
-- Which user's connected accounts to use
11
-- Which toolkits are available
12
-- Which auth configs to use
13
-
14
-Tool Router's meta-tools are the same for everyone. The session determines the context they operate within.
15
-
16
-## Creating a session
17
-
18
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19
-<Tab value="Python">
20
-```python
21
-session = composio.create(user_id="user_123")
22
-```
23
-</Tab>
24
-<Tab value="TypeScript">
25
-```typescript
26
-import { Composio } from '@composio/core';
27
-const composio = new Composio({ apiKey: 'your_api_key' });
28
-// ---cut---
29
-const session = await composio.create("user_123");
30
-```
31
-</Tab>
32
-</Tabs>
33
-
34
-### Enabling toolkits
35
-
36
-Restrict the session to specific toolkits:
37
-
38
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
39
-<Tab value="Python">
40
-```python
41
-# Using array format
42
-session = composio.create(
43
- user_id="user_123",
44
- toolkits=["github", "gmail", "slack"]
45
-)
46
-
47
-# Using object format with enable key
48
-session = composio.create(
49
- user_id="user_123",
50
- toolkits={"enable": ["github", "gmail", "slack"]}
51
-)
52
-```
53
-</Tab>
54
-<Tab value="TypeScript">
55
-```typescript
56
-import { Composio } from '@composio/core';
57
-const composio = new Composio({ apiKey: 'your_api_key' });
58
-// ---cut---
59
-// Using array format
60
-const session = await composio.create("user_123", {
61
- toolkits: ["github", "gmail", "slack"],
62
-});
63
-
64
-// Using object format with enable key
65
-const session2 = await composio.create("user_123", {
66
- toolkits: { enable: ["github", "gmail", "slack"] },
67
-});
68
-```
69
-</Tab>
70
-</Tabs>
71
-
72
-### Disabling toolkits
73
-
74
-Keep all toolkits enabled except specific ones:
75
-
76
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
77
-<Tab value="Python">
78
-```python
79
-session = composio.create(
80
- user_id="user_123",
81
- toolkits={"disable": ["exa", "firecrawl"]}
82
-)
83
-```
84
-</Tab>
85
-<Tab value="TypeScript">
86
-```typescript
87
-import { Composio } from '@composio/core';
88
-const composio = new Composio({ apiKey: 'your_api_key' });
89
-// ---cut---
90
-const session = await composio.create("user_123", {
91
- toolkits: { disable: ["exa", "firecrawl"] },
92
-});
93
-```
94
-</Tab>
95
-</Tabs>
96
-
97
-### Custom auth configs
98
-
99
-Use your own OAuth credentials instead of Composio's defaults:
100
-
101
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
102
-<Tab value="Python">
103
-```python
104
-session = composio.create(
105
- user_id="user_123",
106
- auth_configs={
107
- "github": "ac_your_github_config",
108
- "slack": "ac_your_slack_config"
109
- }
110
-)
111
-```
112
-</Tab>
113
-<Tab value="TypeScript">
114
-```typescript
115
-import { Composio } from '@composio/core';
116
-const composio = new Composio({ apiKey: 'your_api_key' });
117
-// ---cut---
118
-const session = await composio.create("user_123", {
119
- authConfigs: {
120
- github: "ac_your_github_config",
121
- slack: "ac_your_slack_config",
122
- },
123
-});
124
-```
125
-</Tab>
126
-</Tabs>
127
-
128
-See [White-labeling authentication](/docs/guides/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/guides/using-custom-auth-configuration) for toolkits that require your own credentials.
129
-
130
-## Connected accounts
131
-
132
-Connected accounts are stored in Composio and persist across sessions. When a user connects their GitHub account in one session, it remains available in future sessions. Sessions configure *which* connections to use, but don't own the connections themselves.
133
-
134
-### Account selection
135
-
136
-If a user has multiple connected accounts for the same toolkit, you can specify which one to use:
137
-
138
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
139
-<Tab value="Python">
140
-```python
141
-session = composio.create(
142
- user_id="user_123",
143
- connected_accounts={
144
- "gmail": "ca_work_gmail",
145
- "github": "ca_personal_github"
146
- }
147
-)
148
-```
149
-</Tab>
150
-<Tab value="TypeScript">
151
-```typescript
152
-import { Composio } from '@composio/core';
153
-const composio = new Composio({ apiKey: 'your_api_key' });
154
-// ---cut---
155
-const session = await composio.create("user_123", {
156
- connectedAccounts: {
157
- gmail: "ca_work_gmail",
158
- github: "ca_personal_github",
159
- },
160
-});
161
-```
162
-</Tab>
163
-</Tabs>
164
-
165
-### Precedence
166
-
167
-When executing a tool, Tool Router selects the connected account in this order:
168
-
169
-1. `connectedAccounts` override if provided in session config
170
-2. `authConfigs` override - finds or creates connection on that config
171
-3. Auth config previously created by Tool Router for this toolkit
172
-4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
173
-5. Error if no Composio managed auth scheme exists for the toolkit
174
-
175
-If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
176
-
177
-## Session methods
178
-
179
-### mcp
180
-
181
-Get the MCP server URL to use with any MCP-compatible client.
182
-
183
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
184
-<Tab value="Python">
185
-```python
186
-mcp_url = session.mcp.url
187
-```
188
-</Tab>
189
-<Tab value="TypeScript">
190
-```typescript
191
-import { Composio } from '@composio/core';
192
-const composio = new Composio({ apiKey: 'your_api_key' });
193
-const session = await composio.create("user_123");
194
-// ---cut---
195
-const { mcp } = session;
196
-console.log(mcp.url);
197
-```
198
-</Tab>
199
-</Tabs>
200
-
201
-For framework examples, see provider-specific documentation like [OpenAI Agents](/docs/providers/openai-agents) or [Vercel AI SDK](/docs/providers/vercel).
202
-
203
-### tools()
204
-
205
-Get native tools from the session for use with AI frameworks.
206
-
207
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
208
-<Tab value="Python">
209
-```python
210
-tools = session.tools()
211
-```
212
-</Tab>
213
-<Tab value="TypeScript">
214
-```typescript
215
-import { Composio } from '@composio/core';
216
-const composio = new Composio({ apiKey: 'your_api_key' });
217
-const session = await composio.create("user_123");
218
-// ---cut---
219
-const tools = await session.tools();
220
-```
221
-</Tab>
222
-</Tabs>
223
-
224
-### authorize()
225
-
226
-Manually authenticate a user to a toolkit outside of the chat flow.
227
-
228
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
229
-<Tab value="Python">
230
-```python
231
-connection_request = session.authorize("github")
232
-
233
-print(connection_request.redirect_url)
234
-
235
-connected_account = connection_request.wait_for_connection()
236
-```
237
-</Tab>
238
-<Tab value="TypeScript">
239
-```typescript
240
-import { Composio } from '@composio/core';
241
-const composio = new Composio({ apiKey: 'your_api_key' });
242
-const session = await composio.create("user_123");
243
-// ---cut---
244
-const connectionRequest = await session.authorize("github", {
245
- callbackUrl: "https://myapp.com/callback",
246
-});
247
-
248
-console.log(connectionRequest.redirectUrl);
249
-
250
-const connectedAccount = await connectionRequest.waitForConnection();
251
-```
252
-</Tab>
253
-</Tabs>
254
-
255
-For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).
256
-
257
-### toolkits()
258
-
259
-List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
260
-
261
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
262
-<Tab value="Python">
263
-```python
264
-toolkits = session.toolkits()
265
-
266
-for toolkit in toolkits.items:
267
- status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
268
- print(f"{toolkit.name}: {status}")
269
-```
270
-</Tab>
271
-<Tab value="TypeScript">
272
-```typescript
273
-import { Composio } from '@composio/core';
274
-const composio = new Composio({ apiKey: 'your_api_key' });
275
-const session = await composio.create("user_123");
276
-// ---cut---
277
-const toolkits = await session.toolkits();
278
-
279
-toolkits.items.forEach((toolkit) => {
280
- console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
281
-});
282
-```
283
-</Tab>
284
-</Tabs>
285
-
286
-Returns the first 20 toolkits by default.
docs/content/docs/users-and-sessions.mdx
+42
-1
@@ -53,6 +53,47 @@ const session = await composio.create("user_123");
53
</Tab>
54
</Tabs>
55
56
-For details on enabling toolkits, setting auth configs, and selecting connected accounts:
56
+### Session methods
57
+
58
+Once created, a session provides methods to get tools and manage connections:
59
+
60
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
61
+<Tab value="Python">
62
+```python
63
+# Get tools for your AI framework
64
+tools = session.tools()
65
+
66
+# Get MCP server URL
67
+mcp_url = session.mcp.url
68
+
69
+# Authenticate a user to a toolkit
70
+connection_request = session.authorize("github")
71
+
72
+# List available toolkits and their connection status
73
+toolkits = session.toolkits()
74
+```
75
+</Tab>
76
+<Tab value="TypeScript">
77
+```typescript
78
+import { Composio } from '@composio/core';
79
+const composio = new Composio({ apiKey: 'your_api_key' });
80
+const session = await composio.create("user_123");
81
+// ---cut---
82
+// Get tools for your AI framework
83
+const tools = await session.tools();
84
+
85
+// Get MCP server URL
86
+const mcpUrl = session.mcp.url;
87
+
88
+// Authenticate a user to a toolkit
89
+const connectionRequest = await session.authorize("github");
90
+
91
+// List available toolkits and their connection status
92
+const toolkits = await session.toolkits();
93
+```
94
+</Tab>
95
+</Tabs>
96
+
97
+For details on enabling toolkits, setting auth configs, and using session methods:
98
99
<Card title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />