composio.mcp.create / composio.mcp.generate, the “Single Toolkit MCP” flow) who want to migrate to sessions.
Sessions are the next generation of the same idea: you still get an MCP URL that any MCP-compatible client connects to — but instead of standing up and managing a separate server config per toolkit, you create a session that handles tool discovery, authentication, context, and versioning for you.
Starting fresh? Skip this guide and read Configuring Sessions.
Just connecting apps to your own agent for personal use — not building an app? You don’t need the SDK. Use Composio For You to connect across 1000+ apps in a few clicks — switch to it from the product switcher in the top-left of the dashboard. Reserve
session.mcp.url for programmatic, in-app use.What carries over (you keep all of this)
- Your tools — every tool you exposed on a server is available in a session.
- Your auth configs and connected accounts — pass the same
ac_…IDs; your users do not re-authenticate. - The MCP URL pattern — you still get a URL (
session.mcp.url) that plugs into your agent — any MCP-compatible client — the same way, the same protocol. - Per-user isolation — still keyed by
user_id. - Tool restriction — you can still pin a session to an exact, fixed tool list (see Step 3).
What changes
The why: a session is one managed endpoint that replaces N static server configs, gives the agent runtime tool discovery, and keeps context small — without losing the fixed-tool-list behavior you have today if that’s what you want.
Migrating
1
Replace the server config + generate with a session
The two-step “create a server, then generate a per-user URL” collapses into a single Same
composio.create(...). Pass the same toolkit, auth config, and tool list you had on the server.- Python
- TypeScript
- API
user_id + same auth config → existing connected accounts are picked up automatically. No re-auth.2
Point your MCP client at the new URL
Swap the generated server URL for
session.mcp.url wherever your agent connects. Nothing else about the client changes.- Python
- TypeScript
- API
3
Keep an exact, fixed tool list (optional — closest 1:1 with your server)
By default a session gives the agent dynamic tool discovery (meta-tools). If you want the same static behavior as your old server — a fixed set of tools, no discovery — add the direct-tools preset. This preloads exactly the tools you enable and turns meta-tools off.Leave the preset off to get the upgrade: the agent discovers and loads tools at runtime, so you can span many toolkits without bloating context.
- Python
- TypeScript
- API
Beyond the MCP URL
A session isn’t only an MCP endpoint — it’s also a normal SDK object, which is handy for non-agent code paths.Native tools for your framework
session.tools() returns provider-wrapped native tools for OpenAI, Anthropic, LangChain, the Vercel AI SDK, and others, so you skip manual schema wiring. With the direct-tools preset it returns your exact fixed tool set; by default it returns the meta-tools that drive runtime discovery.
- Python
- TypeScript
- API
Execute a tool without an LLM
For a deterministic, non-agent path, call a tool directly on the session.- Python
- TypeScript
- API
Things to know
- Multiple toolkits on one endpoint — where you ran several single-toolkit servers, one session spans them all (
toolkits=["gmail", "slack", "github"]). Fewer moving parts. - Reuse one session — don’t create one per request — sessions persist and are reusable. Create a session once and keep using it across calls; see Configuring Sessions.
- Sharing one account across users — sessions support shared connections (
account_type:"SHARED"+ an allow/deny ACL), pinned per session. See Shared connections. - Tenant-specific params (SharePoint sub-site, Jira subdomain) — prefill them via shared credentials on the auth config.
- White-labeling carries over — pass the same white-labeled auth config IDs; users keep seeing your branding on consent screens. See White-labeling authentication.
- Triggers — unchanged; continue using
composio.triggers.*and webhooks (triggers aren’t part of sessions yet). - Dashboard — sessions are created via the SDK. For no-code, personal app connections, use Composio For You — reachable from the product switcher in the top-left of the dashboard.