Using sessions via MCP

By default Composio gives your agent tools it can call directly. Composio formats them as function schemas for your framework through a provider package. That's what the Quickstart uses, and it's the right choice for most agents.

If you'd rather connect over the Model Context Protocol, every session also exposes a hosted MCP endpoint. This is useful when you want to plug a session into an MCP-native client like Claude Desktop, Cursor, or any framework's MCP transport. No provider package required.

The MCP endpoint

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:

from composio import Composio

composio = Composio()
session = composio.create(user_id="user_123", mcp=True)

mcp_url = session.mcp.url
mcp_headers = session.mcp.headers

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;

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.

A single URL for a fixed set of tools

Combine mcp: true with the direct-tools preset 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.

from composio import Composio, SESSION_PRESET_DIRECT_TOOLS

composio = Composio()

session = composio.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)

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);

Any MCP client pointed at that URL sees only GMAIL_FETCH_EMAILS and GMAIL_CREATE_EMAIL_DRAFT. See Configuring Sessions 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.

from agents import Agent, HostedMCPTool

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",
            }
        )
    ],
)

from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": session.mcp.headers,
        }
    },
)

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 createCustomTool / createCustomToolkit 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 instead of over MCP.

Next