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

# Using sessions via MCP

> Build an application that exposes a Composio session to an MCP-compatible client

Use this guide when you are building an application with Composio and want to expose one user's session over MCP. The application creates and configures the session, then passes its hosted MCP endpoint to a compatible client.

By default, Composio gives your agent tools it can call directly through a [provider package](https://composio-preview.mintlify.site/docs/providers). That is what the [Quickstart](https://composio-preview.mintlify.site/docs/quickstart.md) uses. Set `mcp: true` when an MCP transport fits your application better. No provider package is required for this route.

> [!NOTE]
>
> **Connecting an existing agent instead?**
>
> If you use Codex or Claude Code and did not explicitly choose MCP, install the native [Composio agent plugin](https://composio-preview.mintlify.site/docs/agent-plugins.md). If you explicitly want MCP in an existing client, use [Composio Connect](https://composio-preview.mintlify.site/docs/composio-connect.md).

> [!NOTE]
>
> Want to bring tools from your own remote MCP server into Composio instead? See [Custom MCP](https://composio-preview.mintlify.site/docs/extending-sessions/custom-mcp.md).

## The MCP endpoint

If you use a scoped project API key, enable **Session management** to create and configure sessions and **Session tool execution** for session-linked MCP access. See [API key permissions](https://composio-preview.mintlify.site/reference/authenticating-to-composio/project-api-key-permissions.md) for access levels and routes.

Opt into MCP by passing `mcp: true` when you create the session. The session then exposes its hosted MCP server. Read the URL and headers off `session.mcp`:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
> session = composio.sessions.create(user_id="user_123", mcp=True)
>
> mcp_url = session.mcp.url
> mcp_headers = session.mcp.headers
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio();
> const session = await composio.create("user_123", { mcp: true });
>
> const mcpUrl = session.mcp.url;
> const mcpHeaders = session.mcp.headers;
> ```

> [tab] API
>
> ```bash theme={null}
> # The MCP server accepts the same x-api-key header
> 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"}' | jq -r '.mcp.url'
> ```

You don't need a provider package to use the MCP endpoint, so you can drop it from your `Composio()` setup if MCP is all you need.

> [!NOTE]
>
> Resuming a stored session? Pass the same flag, `composio.use(sessionId, { mcp: true })` (TypeScript) or `composio.use(session_id, mcp=True)` (Python), to surface `session.mcp` on the reused session.

> [!NOTE]
>
> The MCP endpoint and `session.tools()` are backed by the same session. Toolkits, auth configs, and connected accounts you set when [configuring the session](https://composio-preview.mintlify.site/docs/configuring-sessions.md) apply to both.

## Approval without elicitation support

You can [require approval for session tools](https://composio-preview.mintlify.site/docs/configuring-sessions.md#requiring-tool-approval). If your MCP client cannot ask for approval through elicitation, set `experimental.noElicitationSupportFallback` in TypeScript or `experimental.no_elicitation_support_fallback` in Python when creating the session:

* `"deny"` blocks the call when the client cannot ask for approval.
* `"allow"` lets the call run without asking for approval.

For example, pass `experimental: { noElicitationSupportFallback: "deny" }` in TypeScript or `experimental={"no_elicitation_support_fallback": "deny"}` in Python alongside `mcp: true` or `mcp=True`.

## What the MCP headers carry

`session.mcp.headers` holds the credential the SDK used to create or load the session, and nothing else. No other default header and no ambient `COMPOSIO_API_KEY` is copied in.

| SDK credential | Exported header | What it can reach |
| - | - | - |
| Project API key (`apiKey`, `COMPOSIO_API_KEY`, or the project key stored by `composio login`) | `x-api-key` | That one project |
| User API key only (`apiKey: null` with `userApiKey` in TypeScript, `disable_api_key=True` with `user_api_key` in Python, or an `x-user-api-key` default header) | `x-user-api-key` | Every project the user can reach across your organization |

Treat the exported config as a secret and store it where you keep the project API key. A user-only session exports the user's organization-wide key, which makes it the broader credential: prefer a project-key session when an MCP client only needs one project. The SDK also exports `x-org-id` and `x-project-id` when the instance is scoped to a consumer project (see [Run sessions in your organization's consumer project](https://composio-preview.mintlify.site/docs/consumer-agents.md#run-sessions-in-your-organizations-consumer-project)).

The SDK attaches the headers only when the MCP URL has the same origin as the API base URL it talks to, whatever the scheme, so a custom `baseURL` works as long as it serves the session MCP endpoint. For any other destination, `create()` and `use()` called with `mcp: true` (TypeScript) or `mcp=True` (Python) raise `ComposioMCPDestinationError` or `MCPDestinationError`; the error names both origins and never the key. Without the MCP flag the session is still returned, `session.mcp.headers` is empty, and the SDK logs a warning naming both origins, so agents that only use native tools keep working. The SDK never connects to the MCP URL itself and never follows redirects for it. Configure your MCP client so it does not forward these headers to a different origin either.

> [!NOTE]
>
> Requires `@composio/core` ≥ `0.19.1` (TypeScript) or `composio` ≥ `0.22.1` (Python). Earlier releases only exported a project key, so a session driven with a user API key had no usable MCP headers. Pass `session.mcp.headers` through as returned instead of assembling an `x-api-key` header from an environment variable yourself.

## A single URL for a fixed set of tools

Combine `mcp: true` with the [direct-tools preset](https://composio-preview.mintlify.site/docs/configuring-sessions.md) to get one MCP URL that serves exactly the tools you list, with no search or meta tools in front of them. This is the closest equivalent to a classic hosted MCP server scoped to a handful of tools.

> [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,
> )
>
> # A single MCP URL that exposes just these two tools
> print(session.mcp.url)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, SessionPreset } from "@composio/core";
>
> const composio = new Composio();
>
> const session = await composio.create("user_123", {
>   toolkits: ["gmail"],
>   tools: { gmail: { enable: ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"] } },
>   sessionPreset: SessionPreset.DIRECT_TOOLS,
>   mcp: true,
> });
>
> // A single MCP URL that exposes just these two tools
> console.log(session.mcp.url);
> ```

> [tab] API
>
> ```bash theme={null}
> # The SDK's direct-tools preset sends the last five fields; prints a single MCP URL for just these two tools
> 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'
> ```

Any MCP client pointed at that URL sees only `GMAIL_FETCH_EMAILS` and `GMAIL_CREATE_EMAIL_DRAFT`. See [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) for the full set of toolkit, tool, and auth filters.

## Wire it into your framework

Pass `session.mcp.url` and `session.mcp.headers` to your framework's MCP client.

For complete CrewAI and LangChain scripts, follow the [Python MCP research agent example](https://composio-preview.mintlify.site/examples/python-mcp-agents.md).

> [tab] OpenAI Agents
>
> > [tab] Python
> >
> > ```python theme={null}
> > from composio import Composio
> > from agents import Agent, HostedMCPTool
> >
> > composio = Composio()
> > session = composio.create(user_id="user_123", mcp=True)
> >
> > agent = Agent(
> >     name="Assistant",
> >     tools=[
> >         HostedMCPTool(
> >             tool_config={
> >                 "type": "mcp",
> >                 "server_label": "composio",
> >                 "server_url": session.mcp.url,
> >                 "headers": session.mcp.headers,
> >                 "require_approval": "never",
> >             }
> >         )
> >     ],
> > )
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > import { Agent, hostedMcpTool } from '@openai/agents';
> >
> > const composio = new Composio();
> > const session = await composio.create('user_123', { mcp: true });
> > const agent = new Agent({
> >   name: 'Assistant',
> >   tools: [hostedMcpTool({
> >     serverLabel: 'composio',
> >     serverUrl: session.mcp.url,
> >     headers: session.mcp.headers,
> >     requireApproval: 'never',
> >   })],
> > });
> > ```

> [tab] Claude Agent SDK
>
> > [tab] Python
> >
> > ```python theme={null}
> > from composio import Composio
> > from claude_agent_sdk import ClaudeAgentOptions
> >
> > composio = Composio()
> > session = composio.create(user_id="user_123", mcp=True)
> >
> > options = ClaudeAgentOptions(
> >     mcp_servers={
> >         "composio": {
> >             "type": "http",
> >             "url": session.mcp.url,
> >             "headers": session.mcp.headers,
> >         }
> >     },
> > )
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > import type { Options } from '@anthropic-ai/claude-agent-sdk';
> >
> > const composio = new Composio();
> > const session = await composio.create('user_123', { mcp: true });
> > const options: Options = {
> >   mcpServers: {
> >     composio: {
> >       type: 'http',
> >       url: session.mcp.url,
> >       headers: session.mcp.headers,
> >     },
> >   },
> > };
> > ```

> [tab] Vercel AI SDK
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
> import { createMCPClient } from "@ai-sdk/mcp";
>
> const composio = new Composio();
> const { mcp } = await composio.create("user_123", { mcp: true });
>
> const client = await createMCPClient({
>   transport: {
>     type: "http",
>     url: mcp.url,
>     headers: mcp.headers,
>   },
> });
> const tools = await client.tools();
> ```

## Trade-offs

MCP is the more portable option. Any MCP-compatible client connects with just a URL, and it's supported across more frameworks and apps (Claude Desktop, Cursor, the OpenAI Responses API, and others) without a provider package.

The trade-off is that the MCP client talks to Composio's server directly, so anything the SDK does *around* tool execution doesn't apply:

* **Tool-call modifiers don't run.** `beforeExecute` / `afterExecute` hooks and `modifySchema` transforms live in the SDK's execution path. Over MCP the client executes tools against the server and bypasses them, so you can't intercept, reshape, log, or gate calls the way you can with tools your agent calls directly.
* **Session-bound custom tools and toolkits don't work.** Tools created with `experimental_createTool` / `experimental_createToolkit` in TypeScript, or `composio.experimental.tool` / `composio.experimental.Toolkit` in Python, run in your process. The MCP server only exposes Composio's hosted tools, so your local custom tools aren't available over the endpoint.

If you need any of those, call tools directly through a [provider](https://composio-preview.mintlify.site/docs/providers) instead of over MCP.

## Next

> [card] [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md)
>
> Restrict toolkits, set custom auth configs, and select connected accounts
