> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Composio into an existing harness

> You already have a planner and tool search. This wires Composio in underneath them: list toolkits, connect the ones a user picks, load raw schemas into your own index, and execute by slug. Four calls your code makes, with no agent inside your agent.

Most Composio examples hand the agent a session and let Composio's [meta tools](https://composio-preview.mintlify.site/docs/how-composio-works.md#meta-tools) find, authenticate, and run tools. That default works well until you already have your own planner, retrieval index, dispatcher, and permission layer. Then you need the 1000+ apps and managed auth, not another agent inside yours.

Composio sits underneath your harness in four calls:

1. **List toolkits.** [`composio.toolkits.get()`](https://composio-preview.mintlify.site/reference/sdk-reference/typescript/toolkits) returns the catalog independent of any user. That's your integrations directory.
2. **Connect what the user picks.** [`session.authorize(slug)`](https://composio-preview.mintlify.site/docs/authentication) starts the OAuth flow for this user. Bring your own OAuth credentials via [auth configs](https://composio-preview.mintlify.site/docs/authentication/programmatic-auth-configs.md) for a white-label flow, or [import existing tokens](https://composio-preview.mintlify.site/docs/authentication/importing-existing-connections.md) to migrate from another store.
3. **Fetch tools.** Load raw JSON Schema with [`composio.tools.getRawComposioTools({ toolkits })`](https://composio-preview.mintlify.site/docs/configuring-sessions#browsing-the-catalog), or serve the same tools over [MCP](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md) and let your harness call them through the protocol.
4. **Execute by slug.** [`session.execute(slug, args)`](https://composio-preview.mintlify.site/docs/how-composio-works#executing-session-tools) runs one tool as the connected user and hands back data.

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.

```mermaid theme={null}
flowchart LR
  subgraph yours["Your harness"]
    planner[Planner]
    index[Tool index]
    mcpClient[MCP client]
    dispatch[Dispatcher]
  end
  subgraph composio["Composio"]
    toolkits["composio.toolkits.get()"]
    authorize["session.authorize()"]
    schemas["tools.getRawComposioTools()"]
    mcp["session.mcp"]
    execute["session.execute()"]
  end
  ui([Your settings UI]) --> toolkits
  toolkits --> authorize
  toolkits --> schemas
  toolkits --> mcp
  schemas --> index
  index --> planner
  mcp --> mcpClient
  mcpClient --> planner
  planner --> dispatch
  dispatch --> execute
  execute --> planner
```

> [!NOTE]
>
> **Is this the right example for you?**
>
> Read this one if you already own the loop: your own planner, your own tool search or retrieval, your own execution and approval path. You get the app catalog, managed auth, and a single execute call, and Composio stays out of the reasoning.
>
> Read [What is a session?](https://composio-preview.mintlify.site/docs/how-composio-works.md) instead if you'd rather Composio did the discovery. Runtime search returns guidance and recommended steps alongside schemas, keeps a shared context across calls, and costs you far less context than loading hundreds of schemas upfront. That's a real advantage to give up knowingly.

## Setup

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.

> [tab] Python
>
> ```bash uv theme={null}
> uv add composio
> ```
>
> ```bash pip theme={null}
> pip install composio
> ```

> [tab] TypeScript
>
> ```bash npm theme={null}
> npm install @composio/core
> ```
>
> ```bash pnpm theme={null}
> pnpm add @composio/core
> ```
>
> ```bash yarn theme={null}
> yarn add @composio/core
> ```
>
> ```bash bun theme={null}
> bun add @composio/core
> ```

## Create a session your code drives

A [session](https://composio-preview.mintlify.site/docs/how-composio-works.md) 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.

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](https://composio-preview.mintlify.site/docs/configuring-sessions.md#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.

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.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> # user_id is your own identifier, stable for the life of the account
> session = composio.sessions.create(
>     user_id="user_123",
>     manage_connections=False,
>     sandbox={"enable": False},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> // userId is your own identifier, stable for the life of the account
> const session = await composio.create('user_123', {
>   manageConnections: false,
>   sandbox: { enable: false },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # user_id is your own identifier, stable for the life of the account
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "manage_connections": {"enable": false}, "workbench": {"enable": false}}' \
>   | jq -r '.session_id')
> ```

Create one session per user and reuse it. Sessions persist on the server and don't expire, so store the session id on the user record and pick it back up with `composio.use(sessionId)` on later requests. Calling `create()` again just makes another session.

## 1. List the toolkits

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.

> [tab] Python
>
> ```python theme={null}
> page = composio.toolkits.list(limit=50)
>
> for toolkit in page.items:
>     print(f"{toolkit.slug:<20} {toolkit.name}")
>
> # page.next_cursor -> pass back as next_cursor= for the next page
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const toolkits = await composio.toolkits.get({ limit: 50 });
>
> for (const toolkit of toolkits) {
>   console.log(`${toolkit.slug.padEnd(20)} ${toolkit.name}`);
> }
>
> // pass a cursor as { cursor } to request the next page
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET "https://backend.composio.dev/api/v3.1/toolkits?limit=50" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> # Pass the response's next_cursor back as cursor= for the next page
> ```

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.

> [tab] Python
>
> ```python theme={null}
> developer = composio.toolkits.list(category="developer-tools", limit=50)
> connected = session.toolkits(is_connected=True, limit=100)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const session = await composio.create('user_123');
> const developer = await composio.toolkits.get({ category: 'developer-tools', limit: 50 });
> const connected = await session.toolkits({ isConnected: true, limit: 100 });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET "https://backend.composio.dev/api/v3.1/toolkits?category=developer-tools&limit=50" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> curl -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?is_connected=true&limit=100" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

> [!NOTE]
>
> **Toolkits with no auth**
>
> 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.

## 2. Connect what the user picks

`session.authorize(slug)` starts the flow and returns a connection request with a redirect URL. Send the user there. Composio holds the credentials and refreshes them; no token ever lands in your code.

> [tab] Python
>
> ```python theme={null}
> request = session.authorize(
>     "github",
>     callback_url="https://your-app.com/composio/callback",
> )
>
> # Redirect the user here
> print(request.redirect_url)
>
> # Scripts and CLIs can block; a web server should not
> account = request.wait_for_connection()
> print(f"Connected account: {account.id}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const session = await composio.create('user_123');
> const request = await session.authorize('github', {
>   callbackUrl: 'https://your-app.com/composio/callback',
> });
>
> // Redirect the user here
> console.log(request.redirectUrl);
>
> // Scripts and CLIs can block; a web server should not
> const account = await request.waitForConnection();
> console.log(`Connected account: ${account.id}`);
> ```

> [tab] API
>
> ```bash theme={null}
> # Redirect the user to the returned redirect_url
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit": "github", "callback_url": "https://your-app.com/composio/callback"}'
> ```

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.

> [!NOTE]
>
> **White-label OAuth and migrating apps**
>
> 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.
>
> > [tab] Python
> >
> > ```python theme={null}
> > import os
> > from typing import cast
> > from composio.client.types import auth_config_create_params as auth_types
> >
> > auth_config = composio.auth_configs.create(
> >     toolkit="github",
> >     options={
> >         "type": "use_custom_auth",
> >         "auth_scheme": "OAUTH2",
> >         "name": "My GitHub App",
> >         # The generated credentials type omits OAuth client fields accepted by the API.
> >         "credentials": cast(auth_types.AuthConfigUnionMember1Credentials, {
> >             "client_id": os.environ["GITHUB_CLIENT_ID"],
> >             "client_secret": os.environ["GITHUB_CLIENT_SECRET"],
> >             "oauth_redirect_uri": "https://backend.composio.dev/api/v1/auth-apps/add",
> >         }),
> >     },
> > )
> >
> > session = composio.sessions.create(
> >     user_id="user_123",
> >     toolkits=["github"],
> >     auth_configs={"github": auth_config.id},
> >     manage_connections=False,
> >     sandbox={"enable": False},
> > )
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > const composio = new Composio();
> > const authConfig = await composio.authConfigs.create('github', {
> >   type: 'use_custom_auth',
> >   authScheme: 'OAUTH2',
> >   name: 'My GitHub App',
> >   credentials: {
> >     client_id: process.env.GITHUB_CLIENT_ID!,
> >     client_secret: process.env.GITHUB_CLIENT_SECRET!,
> >     oauth_redirect_uri: 'https://backend.composio.dev/api/v1/auth-apps/add',
> >   },
> > });
> >
> > const session = await composio.sessions.create('user_123', {
> >   toolkits: ['github'],
> >   authConfigs: { github: authConfig.id },
> >   manageConnections: false,
> >   sandbox: { enable: false },
> > });
> > ```
>
> > [tab] API
> >
> > ```bash theme={null}
> > AUTH_CONFIG_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/auth_configs \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{
> >     "toolkit": {"slug": "github"},
> >     "auth_config": {
> >       "type": "use_custom_auth",
> >       "authScheme": "OAUTH2",
> >       "name": "My GitHub App",
> >       "credentials": {
> >         "client_id": "'"$GITHUB_CLIENT_ID"'",
> >         "client_secret": "'"$GITHUB_CLIENT_SECRET"'",
> >         "oauth_redirect_uri": "https://backend.composio.dev/api/v1/auth-apps/add"
> >       }
> >     }
> >   }' | jq -r '.auth_config.id')
> >
> > SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{
> >     "user_id": "user_123",
> >     "toolkits": {"enable": ["github"]},
> >     "auth_configs": {"github": "'"$AUTH_CONFIG_ID"'"},
> >     "manage_connections": {"enable": false},
> >     "workbench": {"enable": false}
> >   }' | jq -r '.session_id')
> > ```
>
> 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.

## 3. Fetch tools

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.

### Option A: Raw JSON Schema

`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.

> [tab] Python
>
> ```python theme={null}
> connected = session.toolkits(is_connected=True, limit=100)
> slugs = [toolkit.slug for toolkit in connected.items]
>
> tools = composio.tools.get_raw_composio_tools(toolkits=slugs)
>
> for tool in tools:
>     index.add(
>         name=tool.slug,                    # "GITHUB_CREATE_AN_ISSUE"
>         description=tool.description,
>         parameters=tool.input_parameters,  # JSON Schema
>     )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const session = await composio.create('user_123');
> declare const index: {
>   add(entry: { name: string; description?: string; parameters?: unknown }): void;
> };
> const connected = await session.toolkits({ isConnected: true, limit: 100 });
> const slugs = connected.items.map(toolkit => toolkit.slug);
>
> const tools = await composio.tools.getRawComposioTools({
>   toolkits: slugs,
>   important: false,
> });
>
> for (const tool of tools) {
>   index.add({
>     name: tool.slug,                  // "GITHUB_CREATE_AN_ISSUE"
>     description: tool.description,
>     parameters: tool.inputParameters, // JSON Schema
>   });
> }
> ```

> [tab] API
>
> ```bash theme={null}
> SLUGS=$(curl -s -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?is_connected=true&limit=100" \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   | jq -r '[.items[].slug] | join(",")')
>
> # Each item has slug, description, and input_parameters (JSON Schema)
> curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=$SLUGS" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

> [!WARNING]
>
> **Pass `important: false` to fetch every tool, not a curated subset**
>
> In TypeScript, `getRawComposioTools({ toolkits })` applies Composio's `important` flag on your behalf and returns a hand-picked subset of each toolkit rather than all of it. Nothing errors; the list is just shorter than the toolkit, which is a bad surprise to find in an index weeks later. The auto-apply is suppressed by `important: false` and by passing any of `tools`, `tags`, `search`, or `limit`, so a call that already sets a large `limit` is getting the full list. The Python method has no `important` parameter and always returns the unfiltered list.
>
> Which you want depends on your index. Curated is a reasonable default for semantic search over a few toolkits. Full is what you want when your planner needs to name an exact tool.

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.

### Option B: MCP server

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.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
>
> composio = Composio()
>
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["gmail"],
>     tools={
>         "gmail": {
>             "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
>         },
>     },
>     session_preset=SESSION_PRESET_DIRECT_TOOLS,
>     mcp=True,
> )
>
> print(session.mcp.url)
> print(session.mcp.headers)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, SessionPreset } from '@composio/core';
>
> const composio = new Composio();
>
> const session = await composio.sessions.create('user_123', {
>   toolkits: ['gmail'],
>   tools: {
>     gmail: {
>       enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
>     },
>   },
>   sessionPreset: SessionPreset.DIRECT_TOOLS,
>   mcp: true,
> });
>
> console.log(session.mcp.url);
> console.log(session.mcp.headers);
> ```

> [tab] API
>
> ```bash theme={null}
> # The direct-tools preset is these settings: no connection manager, sandbox,
> # search, or multi-execute, and every allowed tool preloaded
> curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["gmail"]},
>     "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}},
>     "manage_connections": {"enable": false},
>     "workbench": {"enable": false},
>     "preload": {"tools": "all"},
>     "search": {"enable": false},
>     "execute": {"enable_multi_execute": false}
>   }' | jq -r '.mcp.url'
>
> # MCP clients authenticate to that URL with the same x-api-key header
> ```

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](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md).

> [accordion] Alternative: let the session decide which tools exist
>
> `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.
>
> The trade-off is that every change to the exposed set becomes a session update rather than a local filter, and the returned list includes any meta tools the session still has enabled.

### Keep the session in step with what you indexed

If you scoped the session to specific toolkits, that filter is what gates execution later. When a user connects something new, widen the session rather than creating another one. `session.update()` is a patch: fields you omit are left alone.

> [tab] Python
>
> ```python theme={null}
> session.update(toolkits={"enable": [*slugs, "linear"]})
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const session = await composio.create('user_123');
> declare const slugs: string[];
> await session.update({ toolkits: { enable: [...slugs, 'linear'] } });
> ```

> [tab] API
>
> ```bash theme={null}
> # List the toolkits already in your index, plus the new one
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkits": {"enable": ["github", "linear"]}}'
> ```

A session created with no toolkit filter, as in the setup above, already allows everything and needs no update.

## 4. Execute by slug

Your planner picked a tool and produced arguments. `session.execute` runs it as this user's connected account and returns the result. No model, no retry loop, no interpretation.

> [tab] Python
>
> ```python theme={null}
> result = session.execute(
>     "GITHUB_CREATE_AN_ISSUE",
>     arguments={
>         "owner": "ComposioHQ",
>         "repo": "composio",
>         "title": "Tool schemas drift between staging and prod",
>         "body": "Filed by the harness.",
>     },
> )
>
> if result.result_type == "failed":
>     raise RuntimeError(result.error or f"Tool execution failed (log ID: {result.log_id})")
>
> print(result.data)
> print(result.log_id)  # look this up in the dashboard
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio();
> const session = await composio.create('user_123');
> const result = await session.execute('GITHUB_CREATE_AN_ISSUE', {
>   owner: 'ComposioHQ',
>   repo: 'composio',
>   title: 'Tool schemas drift between staging and prod',
>   body: 'Filed by the harness.',
> });
>
> if (result.resultType === 'failed') {
>   throw new Error(result.error || `Tool execution failed (log ID: ${result.logId})`);
> }
>
> console.log(result.data);
> console.log(result.logId); // look this up in the dashboard
> ```

> [tab] API
>
> ```bash theme={null}
> # The response carries result_type, data, error, and log_id
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "tool_slug": "GITHUB_CREATE_AN_ISSUE",
>     "arguments": {
>       "owner": "ComposioHQ",
>       "repo": "composio",
>       "title": "Tool schemas drift between staging and prod",
>       "body": "Filed by the harness."
>     }
>   }'
> ```

Check `resultType` (`result_type` in Python), not `error`, to tell whether execution succeeded. A failed execution can have null or empty error text. The tool-specific `data` payload has no guaranteed `successful` field. See [Reading execution results](https://composio-preview.mintlify.site/docs/how-composio-works.md#reading-execution-results) for the result envelope.

Transport failures, cancellation, and [requests for user input](https://composio-preview.mintlify.site/docs/how-composio-works.md#handling-requests-for-user-input) can raise exceptions instead of returning a result. `logId` (`log_id` in Python) ties the call to its entry in the dashboard so you can inspect what Composio sent upstream.

When the thing you need isn't wrapped as a tool, [`session.proxyExecute()`](https://composio-preview.mintlify.site/docs/extending-sessions/proxy-execute) calls the raw API endpoint under the same connected account.

## What maps to what

| Your harness | Composio |
| - | - |
| Integrations directory | `composio.toolkits.get()` / `composio.toolkits.list()` |
| Per-user connection state | `session.toolkits()` |
| "Connect" button | `session.authorize(slug)` |
| White-label OAuth app | `authConfigs` at session creation |
| Tool index or retrieval corpus | `composio.tools.getRawComposioTools({ toolkits, important: false })` |
| MCP tool server | `session.mcp` |
| Tool dispatch | `session.execute(slug, args)` |
| Per-user isolation | one session per user id |
| Audit trail | `result.logId` |

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.

> [!NOTE]
>
> **If the tool set is fixed**
>
> A harness with a known, small tool set doesn't need step three at all. Create the session with the [direct tools preset](https://composio-preview.mintlify.site/docs/configuring-sessions.md#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.

> [card] [Configuring sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md)
>
> Every filter a session takes: toolkits, tools, tags, auth configs, connected accounts

> [card] [What is a session?](https://composio-preview.mintlify.site/docs/how-composio-works.md)
>
> The runtime context behind all four calls, and what the meta tools do when you leave them on

> [card] [Authentication](https://composio-preview.mintlify.site/docs/authentication)
>
> Managed auth, your own OAuth credentials, and pre-connecting accounts

> [card] [Proxy execute](https://composio-preview.mintlify.site/docs/extending-sessions/proxy-execute.md)
>
> Call an API endpoint Composio doesn't wrap, as the connected account
