Migrating from MCP servers to Sessions

This guide is for developers using Composio's MCP servers (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.

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

from composio import Composio

composio = Composio(api_key="YOUR_API_KEY")

# Before: create a server config, then generate a per-user URL
# server = composio.mcp.create(
#     name="my-gmail-server",
#     toolkits=[{"toolkit": "gmail", "auth_config": "ac_xyz123"}],
#     allowed_tools=["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
# )
# instance = composio.mcp.generate(user_id="user-123", mcp_config_id=server.id)
# mcp_url = instance["url"]

# After: one session, same toolkit + auth config + tools
session = composio.create(
    user_id="user-123",
    toolkits=["gmail"],
    auth_configs={"gmail": "ac_xyz123"},
    tools={"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]}},
)
mcp_url = session.mcp.url

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });

// Before: create a server config, then generate a per-user URL
// const server = await composio.mcp.create("my-gmail-server", {
//   toolkits: [{ toolkit: "gmail", authConfigId: "ac_xyz123" }],
//   allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
// });
// const instance = await composio.mcp.generate("user-123", server.id);
// const mcpUrl = instance.url;

// After: one session, same toolkit + auth config + tools
const session = await composio.create("user-123", {
  toolkits: ["gmail"],
  authConfigs: { gmail: "ac_xyz123" },
  tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] } },
});
const { mcp } = session;
const mcpUrl = mcp.url;

# Before: https://backend.composio.dev/v3/mcp/<SERVER_ID>?user_id=<USER_ID>
# After:  session.mcp.url

from composio import Composio, SESSION_PRESET_DIRECT_TOOLS

session = composio.create(
    user_id="user-123",
    toolkits=["gmail"],
    auth_configs={"gmail": "ac_xyz123"},
    tools={"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]}},
    session_preset=SESSION_PRESET_DIRECT_TOOLS,
)

const session = await composio.create("user-123", {
  toolkits: ["gmail"],
  authConfigs: { gmail: "ac_xyz123" },
  tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] } },
  sessionPreset: SessionPreset.DIRECT_TOOLS,
});

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.

tools = session.tools()

const tools = await session.tools();

Execute a tool without an LLM

For a deterministic, non-agent path, call a tool directly on the session.

result = session.execute(
    "GITHUB_CREATE_ISSUE",
    arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"},
)

const result = await session.execute("GITHUB_CREATE_ISSUE", {
  owner: "my-org",
  repo: "my-repo",
  title: "Fix login bug",
});

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.

Get started