- List toolkits.
composio.toolkits.get()returns the catalog independent of any user. That’s your integrations directory. - Connect what the user picks.
session.authorize(slug)starts the OAuth flow for this user. Bring your own OAuth credentials via auth configs for a white-label flow, or import existing tokens to migrate from another store. - Fetch tools. Load raw JSON Schema with
composio.tools.getRawComposioTools({ toolkits }), or serve the same tools over MCP and let your harness call them through the protocol. - Execute by slug.
session.execute(slug, args)runs one tool as the connected user and hands back data.
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? 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 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.- Python
- TypeScript
Create a session your code drives
A session 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 callssession.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 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.
- Python
- TypeScript
- API
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.
- Python
- TypeScript
- API
session.toolkits() with the same toolkit list; it merges the global catalog with per-user connection state.
- Python
- TypeScript
- API
Toolkits with no authToolkits 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.
- Python
- TypeScript
- API
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.
White-label OAuth and migrating appsBy default, To migrate users from an existing token store, create a connected account directly with
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.- Python
- TypeScript
- API
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.
- Python
- TypeScript
- API
Option B: MCP server
Create a session withmcp: 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.
- Python
- TypeScript
- API
Alternative: let the session decide which tools exist
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.
- Python
- TypeScript
- API
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.
- Python
- TypeScript
- API
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 for the result envelope.
Transport failures, cancellation, and 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() calls the raw API endpoint under the same connected account.
What maps to what
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.
If the tool set is fixedA harness with a known, small tool set doesn’t need step three at all. Create the session with the 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.