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

# Migrating from MCP servers to Sessions

> Move from per-toolkit MCP server configs to the sessions paradigm

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

> [!WARNING]
>
> `composio.mcp.generate()` warns once that its URLs depend on the deprecated `include_composio_helper_actions` query parameter. Use a Session's `session.mcp.url` instead, as shown below.

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.

> [!NOTE]
>
> Starting fresh? Skip this guide and read [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md).

> [!NOTE]
>
> 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

| | MCP servers (today) | Sessions |
| - | - | - |
| **Setup** | Create + manage a server config per toolkit (`composio.mcp.create`) | One `composio.create(user_id)` — no server object to manage |
| **Get a URL** | `composio.mcp.generate(user_id, mcp_config_id)` → `instance.url` | `session.mcp.url` |
| **Tools** | Fixed `allowed_tools` list, baked into the server | Dynamic discovery by default, **or** a fixed list (direct-tools preset) — your choice |
| **Multiple toolkits** | One server per toolkit | One session spans many toolkits |
| **Context** | All allowed tools always loaded | Managed — search/preload keep the agent's context lean |
| **Versioning** | Manual | Handled automatically |
| **Auth** | Pre-authenticate, then generate | Carries over; in-chat auth available, or `session.authorize()` |

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 `composio.create(...)`. Pass the **same** toolkit, auth config, and tool list you had on the server.

> [tab] Python
>
> ```python theme={null}
> 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=True,
> )
> mcp_url = session.mcp.url
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> 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"] } },
>   mcp: true,
> });
> const { mcp } = session;
> const mcpUrl = mcp.url;
> ```

> [tab] API
>
> ```bash theme={null}
> # After: one session, same toolkit + auth config + tools; read mcp.url from the response
> MCP_URL=$(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"]},
>     "auth_configs": {"gmail": "ac_xyz123"},
>     "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]}}
>   }' | jq -r '.mcp.url')
> ```

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

> [!WARNING]
>
> For consumer connections, use `https://connect.composio.dev/mcp`, not this URL.

> [tab] Python
>
> ```python theme={null}
> # Before: https://backend.composio.dev/v3/mcp/<SERVER_ID>?user_id=<USER_ID>
> # After:
> mcp_url = session.mcp.url
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create('user-123', { mcp: true });
> // Before: https://backend.composio.dev/v3/mcp/<SERVER_ID>?user_id=<USER_ID>
> // After:
> const mcpUrl = session.mcp.url;
> ```

> [tab] API
>
> ```bash theme={null}
> # Before: https://backend.composio.dev/v3/mcp/<SERVER_ID>?user_id=<USER_ID>
> # After: SESSION_ID is the session_id returned when you created the session
> MCP_URL=$(curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.mcp.url')
> ```

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

> [tab] Python
>
> ```python theme={null}
> 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,
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, SessionPreset } from '@composio/core';
>
> const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
> 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,
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # The direct-tools preset is an SDK shorthand; send the settings it expands to
> curl -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"]},
>     "auth_configs": {"gmail": "ac_xyz123"},
>     "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"]}},
>     "manage_connections": {"enable": false},
>     "workbench": {"enable": false},
>     "preload": {"tools": "all"},
>     "search": {"enable": false},
>     "execute": {"enable_multi_execute": false}
>   }'
> ```

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.

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

> [tab] Python
>
> ```python theme={null}
> tools = session.tools()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
> const session = await composio.create("user-123");
> const tools = await session.tools();
> ```

> [tab] API
>
> ```bash theme={null}
> # SESSION_ID is the session_id returned when you created the session.
> # The API returns raw tool schemas; the SDK wraps them for your provider.
> curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

### Execute a tool without an LLM

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

> [tab] Python
>
> ```python theme={null}
> result = session.execute(
>     "GITHUB_CREATE_ISSUE",
>     arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
> const session = await composio.create("user-123");
> const result = await session.execute("GITHUB_CREATE_ISSUE", {
>   owner: "my-org",
>   repo: "my-repo",
>   title: "Fix login bug",
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # SESSION_ID is the session_id returned when you created the session
> 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_ISSUE",
>     "arguments": {"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](https://composio-preview.mintlify.site/docs/configuring-sessions.md).
* **Sharing one account across users** — sessions support **shared connections** (`account_type:"SHARED"` + an allow/deny ACL), pinned per session. See [Shared connections](https://composio-preview.mintlify.site/docs/extending-sessions/shared-connections.md).
* **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](https://composio-preview.mintlify.site/docs/authentication/white-labeling-authentication.md).
* **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.

## Next

> [card] [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md)
>
> Toolkits, auth configs, account selection, presets, and session methods
