Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Apply updates from Soham's feedback
Brendan O'Leary committed
Aug 28, 2026 at 13:20 UTC
582b837fd1e143a5148b873481b4baad4dd12902
1 file changed
+149
-28
docs/content/examples/harness-integration.mdx
+149
-28
@@ -14,9 +14,9 @@ Most Composio examples hand the agent a session and let Composio's [meta tools](
14
15
Composio sits underneath your harness in four calls:
16
17
-1. **List toolkits.** [`session.toolkits()`](/docs/configuring-sessions#toolkits) returns the catalog with each toolkit's live connection state for this user. That's your integrations directory.
18
-2. **Connect what the user picks.** [`session.authorize(slug)`](/docs/authentication) returns a redirect URL. Composio owns the OAuth dance, the token storage, and the refresh.
19
-3. **Load raw tool schemas.** [`composio.tools.getRawComposioTools({ toolkits })`](/docs/configuring-sessions#browsing-the-catalog) returns plain JSON Schema. Feed it to whatever index your planner already searches.
17
+1. **List toolkits.** [`composio.toolkits.get()`](/reference/sdk-reference/typescript/toolkits) returns the catalog independent of any user. That's your integrations directory.
18
+2. **Connect what the user picks.** [`session.authorize(slug)`](/docs/authentication) starts the OAuth flow for this user. Bring your own OAuth credentials via [auth configs](/docs/authentication/programmatic-auth-configs) for a white-label flow, or [import existing tokens](/docs/authentication/importing-existing-connections) to migrate from another store.
19
+3. **Fetch tools.** Load raw JSON Schema with [`composio.tools.getRawComposioTools({ toolkits })`](/docs/configuring-sessions#browsing-the-catalog), or serve the same tools over [MCP](/docs/sessions-via-mcp) and let your harness call them through the protocol.
20
4. **Execute by slug.** [`session.execute(slug, args)`](/docs/how-composio-works#executing-session-tools) runs one tool as the connected user and hands back data.
21
22
Nothing here asks a model to make a decision. Every call is one your code makes, at a moment you choose, because your planner decided.
@@ -25,19 +25,24 @@ Nothing here asks a model to make a decision. Every call is one your code makes,
25
subgraph yours["Your harness"]
26
planner[Planner]
27
index[Tool index]
28
+ mcpClient[MCP client]
29
dispatch[Dispatcher]
30
end
31
subgraph composio["Composio"]
31
- toolkits["session.toolkits()"]
32
+ toolkits["composio.toolkits.get()"]
33
authorize["session.authorize()"]
34
schemas["tools.getRawComposioTools()"]
35
+ mcp["session.mcp"]
36
execute["session.execute()"]
37
end
38
ui([Your settings UI]) --> toolkits
39
toolkits --> authorize
38
- authorize --> schemas
40
+ toolkits --> schemas
41
+ toolkits --> mcp
42
schemas --> index
43
index --> planner
44
+ mcp --> mcpClient
45
+ mcpClient --> planner
46
planner --> dispatch
47
dispatch --> execute
48
execute --> planner
@@ -52,22 +57,31 @@ Read [What is a session?](/docs/how-composio-works) instead if you'd rather Comp
57
58
## Setup
59
55
-You need a [Composio API key](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=examples-agent-harness) and a user id from your own database. There's no model provider in this example: your harness already has one.
60
+You need a [Composio API key](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=examples-agent-harness) to list the catalog and drive sessions. Listing apps does not need a user id; creating a session and connecting accounts does. There's no model provider in this example: your harness already has one.
61
57
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
62
+<Tabs groupId="language" items={['Python', 'TypeScript', 'Go']} persist>
63
<Tab value="Python">
64
<PackageInstall packages="composio" ecosystem="python" />
65
</Tab>
66
<Tab value="TypeScript">
67
<PackageInstall packages="@composio/core" />
68
</Tab>
69
+<Tab value="Go">
70
+```bash
71
+go get github.com/ComposioHQ/composio-go
72
+```
73
+
74
+See the [Go SDK usage example](https://github.com/ComposioHQ/composio-go#usage-example).
75
+</Tab>
76
</Tabs>
77
78
## Create a session your code drives
79
80
A [session](/docs/how-composio-works) is the per-user context: which toolkits are in play, which accounts are connected, what may run. You still want one. What changes is that nothing on it ever reaches a model. Your harness never calls `session.tools()`, so the search and execute meta tools sit on the session unused.
81
70
-Two settings are still worth passing at creation. `manageConnections: false` drops the connection meta-tools, because your settings page is doing that job. [Disabling the sandbox](/docs/configuring-sessions#disabling-the-sandbox) drops the code-execution tools, because your harness runs its own code. Leave the toolkit filter open and the session can see the whole catalog, which is what step one needs.
82
+Two settings are still worth passing at creation. `manageConnections: false` drops the connection meta-tools, because your settings page is doing that job. [Disabling the sandbox](/docs/configuring-sessions#disabling-the-sandbox) drops the code-execution tools, because your harness runs its own code. Leave the toolkit filter open and the session can execute any tool your planner names.
83
+
84
+If you want a white-label flow, pass `authConfigs` at creation to pin the session to your own OAuth app. `session.authorize()` then sends the user through your consent screen instead of Composio's managed app. You can update those configs later, so migrating from a default app to your own app is a session patch, not a rebuild.
85
86
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
87
<Tab value="Python">
@@ -103,18 +117,15 @@ Create one session per user and reuse it. Sessions persist on the server and don
117
118
## 1. List the toolkits
119
106
-`session.toolkits()` is the catalog *and* the connection state, in one paginated call. Each item carries the toolkit's slug and name, whether it needs auth at all, and whether this user has a live connection. That's everything an integrations page needs to render.
120
+The catalog does not belong to a user. `composio.toolkits.list()` in Python or `composio.toolkits.get()` in TypeScript returns the app list independent of any session, so your integrations page can render before anyone signs in.
121
122
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
123
<Tab value="Python">
124
```python
111
-page = session.toolkits(limit=50)
125
+page = composio.toolkits.list(limit=50)
126
127
for toolkit in page.items:
114
- connected = toolkit.is_no_auth or bool(
115
- toolkit.connection and toolkit.connection.is_active
116
- )
117
- print(f"{'connected' if connected else 'available':<10} {toolkit.slug:<20} {toolkit.name}")
128
+ print(f"{toolkit.slug:<20} {toolkit.name}")
129
130
# page.next_cursor -> pass back as next_cursor= for the next page
131
```
@@ -123,15 +134,11 @@ for toolkit in page.items:
134
```typescript
135
import { Composio } from '@composio/core';
136
const composio = new Composio();
126
-const session = await composio.create('user_123');
137
// ---cut---
128
-const page = await session.toolkits({ limit: 50 });
138
+const page = await composio.toolkits.get({ limit: 50 });
139
140
for (const toolkit of page.items) {
131
- const connected = toolkit.isNoAuth || toolkit.connection?.isActive === true;
132
- console.log(
133
- `${connected ? 'connected' : 'available'} ${toolkit.slug.padEnd(20)} ${toolkit.name}`
134
- );
141
+ console.log(`${toolkit.slug.padEnd(20)} ${toolkit.name}`);
142
}
143
144
// page.cursor -> pass back as { cursor } for the next page
@@ -139,12 +146,12 @@ for (const toolkit of page.items) {
146
</Tab>
147
</Tabs>
148
142
-Two filters matter for a real UI. `search` does the searching for you, so a user typing "issue tracker" gets Linear and Jira without you shipping a fuzzy match over 1000+ slugs. `isConnected` narrows to accounts that are actually live, which is the list step three works from.
149
+Filter by category or sort alphabetically. If you also need to know whether this user has a live connection, call `session.toolkits()` with the same toolkit list; it merges the global catalog with per-user connection state.
150
151
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
152
<Tab value="Python">
153
```python
147
-matches = session.toolkits(search="issue tracker", limit=10)
154
+developer = composio.toolkits.list(category="developer-tools", limit=50)
155
connected = session.toolkits(is_connected=True, limit=100)
156
```
157
</Tab>
@@ -154,14 +161,14 @@ import { Composio } from '@composio/core';
161
const composio = new Composio();
162
const session = await composio.create('user_123');
163
// ---cut---
157
-const matches = await session.toolkits({ search: 'issue tracker', limit: 10 });
164
+const developer = await composio.toolkits.get({ category: 'developer-tools', limit: 50 });
165
const connected = await session.toolkits({ isConnected: true, limit: 100 });
166
```
167
</Tab>
168
</Tabs>
169
170
<Callout type="info" title="Toolkits with no auth">
164
-Toolkits where `isNoAuth` is true (search, scrapers, and similar) come back with no `connection` object at all, because there's nothing to connect. Treat them as always available or your list will show a permanently disconnected Exa.
171
+Toolkits where `isNoAuth` is true (search, scrapers, and similar) need no connection. They show up in the global catalog and, if you use `session.toolkits()`, come back with no `connection` object. Treat them as always available.
172
</Callout>
173
174
## 2. Connect what the user picks
@@ -206,9 +213,68 @@ console.log(`Connected account: ${account.id}`);
213
214
In a web app, don't hold a request open on `waitForConnection`. Point `callbackUrl` at your own route and, when the user lands back on it, confirm with `session.toolkits({ toolkits: ['github'], isConnected: true })`. That check is authoritative and costs one call.
215
209
-## 3. Load raw tool schemas for what's connected
216
+<Callout type="info" title="White-label OAuth and migrating apps">
217
+By default, `session.authorize()` uses Composio's managed OAuth app. To brand the consent screen or control the OAuth client, create an auth config with your own credentials and pass it at session creation.
218
+
219
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
220
+<Tab value="Python">
221
+```python
222
+auth_config = composio.auth_configs.create(
223
+ toolkit="github",
224
+ options={
225
+ "type": "use_custom_auth",
226
+ "auth_scheme": "OAUTH2",
227
+ "name": "My GitHub App",
228
+ "credentials": {
229
+ "client_id": os.environ["GITHUB_CLIENT_ID"],
230
+ "client_secret": os.environ["GITHUB_CLIENT_SECRET"],
231
+ "oauth_redirect_uri": "https://backend.composio.dev/api/v1/auth-apps/add",
232
+ },
233
+ },
234
+)
235
+
236
+session = composio.sessions.create(
237
+ user_id="user_123",
238
+ toolkits=["github"],
239
+ auth_configs={"github": auth_config.id},
240
+ manage_connections=False,
241
+ sandbox={"enable": False},
242
+)
243
+```
244
+</Tab>
245
+<Tab value="TypeScript">
246
+```typescript
247
+const authConfig = await composio.authConfigs.create('github', {
248
+ type: 'use_custom_auth',
249
+ authScheme: 'OAUTH2',
250
+ name: 'My GitHub App',
251
+ credentials: {
252
+ client_id: process.env.GITHUB_CLIENT_ID,
253
+ client_secret: process.env.GITHUB_CLIENT_SECRET,
254
+ oauth_redirect_uri: 'https://backend.composio.dev/api/v1/auth-apps/add',
255
+ },
256
+});
257
+
258
+const session = await composio.sessions.create('user_123', {
259
+ toolkits: ['github'],
260
+ authConfigs: { github: authConfig.id },
261
+ manageConnections: false,
262
+ sandbox: { enable: false },
263
+});
264
+```
265
+</Tab>
266
+</Tabs>
267
+
268
+To migrate users from an existing token store, create a connected account directly with `composio.connectedAccounts.initiate()` (TypeScript) or `composio.connected_accounts.initiate()` (Python). You can update `authConfigs` on the session later, so moving from the default app to your own app is a patch rather than a rebuild.
269
+</Callout>
270
+
271
+## 3. Fetch tools
272
+
273
+Your harness can consume tools in two shapes. Load raw JSON Schema and call them yourself, or expose them through an MCP server and let your harness call them over the protocol.
274
+
275
+### Option A: Raw JSON Schema
276
211
-This is the step that plugs into your index. `getRawComposioTools` returns tool definitions with no user context and no provider wrapping: a slug, a name, a description, and input parameters as plain JSON Schema. Take the connected toolkits from step one, pull their tools, and write them into whatever corpus your planner already searches.
277
+`getRawComposioTools` returns tool definitions with no user context and no provider wrapping: a slug, a name, a description, and input parameters as plain JSON Schema. Take the toolkits you want to expose, pull their tools, and write them into whatever corpus your planner already searches.
278
279
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
280
<Tab value="Python">
@@ -262,6 +328,58 @@ Which you want depends on your index. Curated is a reasonable default for semant
328
329
Fetch per toolkit rather than in one shot once a user has a lot connected. Thirty toolkits at full breadth is several thousand schemas, and you almost certainly want them cached, keyed by toolkit and refreshed on your own schedule, rather than pulled on every turn.
330
331
+### Option B: MCP server
332
+
333
+Create a session with `mcp: true` and hand `session.mcp.url` (and `session.mcp.headers` if required) to any MCP client. The server exposes the same tools and executes them under the session's connected accounts, so your harness talks the protocol instead of calling `session.execute()` directly.
334
+
335
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
336
+<Tab value="Python">
337
+```python
338
+from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
339
+
340
+composio = Composio()
341
+
342
+session = composio.sessions.create(
343
+ user_id="user_123",
344
+ toolkits=["gmail"],
345
+ tools={
346
+ "gmail": {
347
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
348
+ },
349
+ },
350
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
351
+ mcp=True,
352
+)
353
+
354
+print(session.mcp.url)
355
+print(session.mcp.headers)
356
+```
357
+</Tab>
358
+<Tab value="TypeScript">
359
+```typescript
360
+import { Composio, SessionPreset } from '@composio/core';
361
+
362
+const composio = new Composio();
363
+
364
+const session = await composio.sessions.create('user_123', {
365
+ toolkits: ['gmail'],
366
+ tools: {
367
+ gmail: {
368
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
369
+ },
370
+ },
371
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
372
+ mcp: true,
373
+});
374
+
375
+console.log(session.mcp.url);
376
+console.log(session.mcp.headers);
377
+```
378
+</Tab>
379
+</Tabs>
380
+
381
+Wire the URL into any MCP client. Examples for OpenAI Agents, Claude Agent SDK, and Vercel AI SDK are in the [sessions via MCP guide](/docs/sessions-via-mcp).
382
+
383
<Accordions>
384
<Accordion title="Alternative: let the session decide which tools exist">
385
`getRawComposioTools` reads the catalog and ignores your session's filters. If you'd rather have one source of truth, scope the session and read its tool list back instead: set `preload: { tools: 'all' }` alongside a toolkit filter, then fetch with `composio.tools.getRawToolRouterSessionTools(session.sessionId)` in TypeScript or `composio.tools.get_raw_tool_router_meta_tools(session.session_id)` in Python. You get exactly the tools the session allows, so the set you index and the set that can execute can't drift apart.
@@ -349,14 +467,17 @@ When the thing you need isn't wrapped as a tool, [`session.proxyExecute()`](/doc
467
468
| Your harness | Composio |
469
| --- | --- |
352
-| Integrations directory | `session.toolkits()` |
470
+| Integrations directory | `composio.toolkits.get()` / `composio.toolkits.list()` |
471
+| Per-user connection state | `session.toolkits()` |
472
| "Connect" button | `session.authorize(slug)` |
473
+| White-label OAuth app | `authConfigs` at session creation |
474
| Tool index or retrieval corpus | `composio.tools.getRawComposioTools({ toolkits, important: false })` |
475
+| MCP tool server | `session.mcp` |
476
| Tool dispatch | `session.execute(slug, args)` |
477
| Per-user isolation | one session per user id |
478
| Audit trail | `result.logId` |
479
359
-Your planner, context window, approval gate, and traces stay the same. Composio takes over OAuth registration, token refresh, schema maintenance, and the execute call that replaces a separate client for each vendor.
480
+Your planner, context window, approval gate, and traces stay the same. Composio takes over the global app catalog, OAuth registration, token refresh, schema maintenance, and the execute path, whether you call `session.execute()` directly or through the MCP server.
481
482
<Callout type="info" title="If the tool set is fixed">
483
A harness with a known, small tool set doesn't need step three at all. Create the session with the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) and an explicit `tools` filter, and `session.tools()` hands back exactly those tools with search, multi-execute, connection management, and the sandbox all off. That's `sessionPreset: SessionPreset.DIRECT_TOOLS` in TypeScript and `session_preset=SESSION_PRESET_DIRECT_TOOLS` in Python. Worth it when the list is short and stable; the four calls above are for when the list is whatever the user connected this morning.