Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add Native Tools vs MCP and Sessions vs Direct Execution guides

Sushmitha Malleshf457fdf87f6f
diff --git a/docs/components/quickstart/integration-tabs.tsx b/docs/components/quickstart/integration-tabs.tsx
index b9296901a..27cb67c38 100644
--- a/docs/components/quickstart/integration-tabs.tsx
+++ b/docs/components/quickstart/integration-tabs.tsx
@@ -1,6 +1,7 @@
'use client';
import Image from 'next/image';
+import Link from 'next/link';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
import { ReactNode } from 'react';
@@ -25,7 +26,7 @@ interface IntegrationTabsProps {
export function IntegrationTabs({ children, defaultValue, tabs = defaultTabs }: IntegrationTabsProps) {
return (
<Tabs defaultValue={defaultValue ?? tabs[0]?.value ?? 'native'} className="not-prose -mt-2">
- <div className="mb-5 flex justify-start">
+ <div className="mb-5 flex items-center gap-3">
<TabsList>
{tabs.map((tab) => (
<TabsTrigger key={tab.value} value={tab.value} className="gap-2">
@@ -51,6 +52,9 @@ export function IntegrationTabs({ children, defaultValue, tabs = defaultTabs }:
</TabsTrigger>
))}
</TabsList>
+ <Link href="/docs/native-tools-vs-mcp" className="text-xs text-fd-muted-foreground hover:text-fd-foreground transition-colors">
+ Which should I use?
+ </Link>
</div>
{children}
</Tabs>
diff --git a/docs/content/docs/common-faq.mdx b/docs/content/docs/common-faq.mdx
index 10cd10448..a6265a0ef 100644
--- a/docs/content/docs/common-faq.mdx
+++ b/docs/content/docs/common-faq.mdx
@@ -70,6 +70,18 @@ The User ID is how Composio identifies your end users. It maps each user to thei
When you create a session with `composio.create(user_id="user_123")`, all connected accounts and tool executions are scoped to that user. See [Users and sessions](/docs/users-and-sessions).
</Accordion>
+<Accordion title="What is the difference between an auth config and an MCP config in the dashboard?">
+An **auth config** defines how users authenticate with a toolkit (OAuth credentials, scopes, API keys). You need one whenever you want users to connect to an app.
+
+An **MCP config** creates a hosted MCP server that exposes specific tools over the Model Context Protocol. It's only needed if you're connecting to Composio from an MCP client like Claude Desktop, Cursor, or OpenAI's Responses API via MCP.
+
+**If you're using the Composio SDK** (sessions or direct execution), you only need auth configs. The SDK handles tool delivery natively. You don't need to create an MCP config.
+
+**If you're using an MCP client**, you need both: an auth config (so users can authenticate) and an MCP config (so the client can discover and call tools over the MCP protocol).
+
+See [Native Tools vs MCP](/docs/native-tools-vs-mcp) for a full comparison.
+</Accordion>
+
<Accordion title="What is an auth config?">
An auth config is a blueprint that defines how authentication works for a toolkit. It specifies the auth method (OAuth2, API Key, etc.), the scopes to request, and the credentials to use.
diff --git a/docs/content/docs/how-composio-works.mdx b/docs/content/docs/how-composio-works.mdx
index 851246b45..f6aaf770d 100644
--- a/docs/content/docs/how-composio-works.mdx
+++ b/docs/content/docs/how-composio-works.mdx
@@ -104,11 +104,15 @@ This keeps the agent's context window lean while still letting it handle operati
## What to read next
-Start with the concepts in order, or jump to the quickstart if you want to build right away:
+Start with the concepts in order, or jump to the quickstart to build right away:
<Cards>
<Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
<Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, discovery, and execution" />
- <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent in 5 minutes" />
+ <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent" />
</Cards>
+
+Deciding how to connect? See:
+- [Native Tools vs MCP](/docs/native-tools-vs-mcp) — SDK vs MCP servers
+- [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) — meta tools vs fetching specific tools
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index d38554654..781c7e982 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -23,6 +23,8 @@
"using-custom-auth-configuration",
"webhook-verification",
"subscribing-to-connection-expiry-events",
+ "native-tools-vs-mcp",
+ "sessions-vs-direct-execution",
"---Features---",
"projects",
"single-toolkit-mcp",
diff --git a/docs/content/docs/migration-guide/direct-to-sessions.mdx b/docs/content/docs/migration-guide/direct-to-sessions.mdx
index a6b8e1e8a..bbfc971a2 100644
--- a/docs/content/docs/migration-guide/direct-to-sessions.mdx
+++ b/docs/content/docs/migration-guide/direct-to-sessions.mdx
@@ -4,7 +4,7 @@ description: Move from direct tool execution to the sessions paradigm
keywords: [migrate, sessions, direct tools, upgrade]
---
-This guide is for developers who are using Composio's **direct tool execution** pattern and want to migrate to **sessions**.
+This guide is for developers who are using Composio's **direct tool execution** pattern and want to migrate to **sessions**. For a comparison of the two patterns, see [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution).
With sessions, you don't need to manage tool fetching, authentication, or execution yourself. You create a session and it handles everything. Your existing auth configs and connected accounts carry over, so your users don't need to re-authenticate.
diff --git a/docs/content/docs/native-tools-vs-mcp.mdx b/docs/content/docs/native-tools-vs-mcp.mdx
new file mode 100644
index 000000000..3ba41dc1e
--- /dev/null
+++ b/docs/content/docs/native-tools-vs-mcp.mdx
@@ -0,0 +1,139 @@
+---
+title: Native Tools vs MCP
+description: When to use Composio's native SDK vs MCP servers
+keywords: [mcp, native tools, function calling, model context protocol, architecture, decision]
+---
+
+**Native tools** give your LLM tool schemas as function definitions. Composio formats them for your specific framework (OpenAI, Anthropic, Vercel AI, etc.) through [provider packages](/docs/providers).
+
+**MCP** exposes tools through the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-compatible client can connect to a Composio MCP server URL. No provider packages needed.
+
+| | Native tools | MCP |
+|---|---|---|
+| **Setup** | [Provider package](/docs/providers) for your framework | SDK or just a URL |
+| **Intercepting tool calls** | Yes, you can log, retry, or require approval before each call | Limited, depends on what the MCP client supports |
+| **Context window** | You control what's loaded | Client loads all tools the server exposes |
+| **Latency** | SDK calls Composio API directly | MCP protocol adds overhead for tool list discovery and each execution |
+
+With native tools, you choose exactly which schemas enter your LLM's context. With MCP, the client pulls the full tool list from the server. A [5-server setup can consume ~55K tokens](https://www.anthropic.com/engineering/advanced-tool-use) before the conversation starts. If you're working with many tools, native tools give you more control over that cost.
+
+## Native tools
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+composio = Composio(provider=OpenAIProvider())
+session = composio.create(user_id="user_123")
+tools = session.tools()
+# Returns meta tools (COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS, etc.)
+# Agent discovers and executes tools at runtime
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+import { OpenAIProvider } from '@composio/openai';
+
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ provider: new OpenAIProvider(),
+});
+const session = await composio.create("user_123");
+const tools = await session.tools();
+// Returns meta tools (COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS, etc.)
+```
+</Tab>
+</Tabs>
+
+## MCP
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio()
+session = composio.create(user_id="user_123")
+
+mcp_url = session.mcp.url
+mcp_headers = session.mcp.headers
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
+const session = await composio.create("user_123");
+
+const mcpUrl = session.mcp.url;
+const mcpHeaders = session.mcp.headers;
+```
+</Tab>
+</Tabs>
+
+Then pass `session.mcp.url` and `session.mcp.headers` to your framework:
+
+<Tabs items={['OpenAI Agents (Python)', 'Claude Agent SDK (Python)', 'Vercel AI SDK (TypeScript)']}>
+<Tab value="OpenAI Agents (Python)">
+```python
+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",
+ }
+ )
+ ],
+)
+```
+</Tab>
+<Tab value="Claude Agent SDK (Python)">
+```python
+from claude_agent_sdk import ClaudeAgentOptions
+
+options = ClaudeAgentOptions(
+ mcp_servers={
+ "composio": {
+ "type": "http",
+ "url": session.mcp.url,
+ "headers": session.mcp.headers,
+ }
+ },
+)
+```
+</Tab>
+<Tab value="Vercel AI SDK (TypeScript)">
+```typescript
+import { createMCPClient } from "@ai-sdk/mcp";
+
+const client = await createMCPClient({
+ transport: {
+ type: "http",
+ url: mcp.url,
+ headers: mcp.headers,
+ },
+});
+const tools = await client.tools();
+```
+</Tab>
+</Tabs>
+
+See the [quickstart](/docs/quickstart) for full working examples.
+
+## Next steps
+
+<Cards>
+ <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build an agent with sessions" />
+ <Card icon={<Key />} title="Providers" href="/docs/providers" description="OpenAI, Anthropic, Vercel AI, LangChain" />
+</Cards>
diff --git a/docs/content/docs/sessions-vs-direct-execution.mdx b/docs/content/docs/sessions-vs-direct-execution.mdx
new file mode 100644
index 000000000..84417536f
--- /dev/null
+++ b/docs/content/docs/sessions-vs-direct-execution.mdx
@@ -0,0 +1,191 @@
+---
+title: Sessions vs Direct Execution
+description: When to use session-based meta tools vs direct tool fetching and execution
+keywords: [session, direct execution, tool router, meta tools, architecture, decision]
+---
+
+**Sessions** give your agent [meta tools](/docs/tools-and-toolkits#meta-tools). The agent discovers which app tools to use, authenticates users, and executes tools at runtime through these meta tools.
+
+**Direct execution** gives your code specific tool schemas. You decide which tools to fetch, manage auth yourself, and call `tools.execute()` directly.
+
+Use sessions unless you need full control over which tools are available and when they run.
+
+| | Sessions | Direct execution |
+|---|---|---|
+| **Discovery** | Agent finds tools at runtime and resolves dependencies automatically (e.g., if a tool needs an ID from another API, the agent finds that tool, runs it, and continues) | You select all tools upfront and need to account for any dependencies between them |
+| **Context cost** | Only meta tools in context, app tools loaded on demand | Every tool schema you select is loaded upfront |
+| **Guidance** | Search returns recommended steps and common pitfalls alongside schemas | You get tool schemas only |
+| **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
+| **Auth** | [In-chat](/docs/authenticating-users/in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authenticating-users/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
+| **[Workbench](/docs/workbench)** | Built in, large responses offloaded automatically | Not available |
+| **Human approval** | You configure approval rules on the session. Harder to intercept individual calls since tools are discovered dynamically | You intercept before each call in your code |
+| **Latency** | Multiple LLM turns (search, then execute) | Single call |
+
+Sessions are configurable. You can [enable or disable specific toolkits](/docs/toolkits/enable-and-disable-toolkits), set [auth configs](/docs/auth-configuration/custom-auth-configs) for white-labeled OAuth, and pin specific [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list.
+
+## Sessions
+
+`composio.create()` returns [meta tools](/docs/tools-and-toolkits#meta-tools):
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+composio = Composio(provider=OpenAIProvider())
+session = composio.create(user_id="user_123")
+tools = session.tools()
+# Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
+# COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+import { OpenAIProvider } from '@composio/openai';
+
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ provider: new OpenAIProvider(),
+});
+const session = await composio.create("user_123");
+const tools = await session.tools();
+// Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
+// COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
+```
+</Tab>
+</Tabs>
+
+The agent discovers app tools through `COMPOSIO_SEARCH_TOOLS`:
+
+```
+User: "Create a GitHub issue for the login bug"
+
+> Agent calls COMPOSIO_SEARCH_TOOLS({ query: "create github issue" })
+ Returns: GITHUB_CREATE_ISSUE schema + connection status
+
+> Agent calls COMPOSIO_MANAGE_CONNECTIONS({ toolkits: ["github"] })
+ Returns: confirms connected (or auth link if not)
+
+> Agent calls COMPOSIO_MULTI_EXECUTE_TOOL({ tool: "GITHUB_CREATE_ISSUE", args: {...} })
+ Returns: issue details
+
+Agent: "Created issue #42 on your-org/your-repo"
+```
+
+<Callout>
+`session.tools()` returns **meta tools** (COMPOSIO_SEARCH_TOOLS, etc.), not app tools (GMAIL_SEND_EMAIL, etc.). The agent discovers app tools at runtime through search. For app tools directly, use direct execution.
+</Callout>
+
+### Configuration
+
+Restrict toolkits, set auth configs, pin connected accounts:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+session = composio.create(
+ user_id="user_123",
+ toolkits=["github", "gmail"],
+ auth_configs={"github": "ac_my_config"},
+ connected_accounts={"gmail": "ca_work"},
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const session = await composio.create("user_123", {
+ toolkits: ["github", "gmail"],
+ authConfigs: { github: "ac_my_config" },
+ connectedAccounts: { gmail: "ca_work" },
+});
+```
+</Tab>
+</Tabs>
+
+See [Configuring Sessions](/docs/configuring-sessions) for details.
+
+## Direct execution
+
+Fetch tools by slug or toolkit. Pass them to your LLM or call `tools.execute()` without one.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+from composio import Composio
+from composio_openai import OpenAIProvider
+
+composio = Composio(provider=OpenAIProvider())
+
+# Fetch specific tools
+tools = composio.tools.get(
+ user_id="user_123",
+ tools=["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"]
+)
+
+# Or by toolkit
+tools = composio.tools.get(
+ user_id="user_123",
+ toolkits=["GITHUB"],
+ limit=50
+)
+
+# Execute without an LLM
+result = composio.tools.execute(
+ "GITHUB_CREATE_ISSUE",
+ user_id="user_123",
+ arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"}
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+import { OpenAIProvider } from '@composio/openai';
+
+const composio = new Composio({
+ apiKey: process.env.COMPOSIO_API_KEY,
+ provider: new OpenAIProvider(),
+});
+
+// Fetch specific tools
+const tools = await composio.tools.get("user_123", {
+ tools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"],
+});
+
+// Or by toolkit
+const allTools = await composio.tools.get("user_123", {
+ toolkits: ["GITHUB"],
+ limit: 50,
+});
+
+// Execute without an LLM
+const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
+ userId: "user_123",
+ arguments: { owner: "my-org", repo: "my-repo", title: "Fix login bug" },
+});
+```
+</Tab>
+</Tabs>
+
+<Callout type="warn">
+`tools.get()` returns 20 tools by default. When fetching from multiple toolkits (e.g., `toolkits=["GMAIL", "GITHUB", "TAVILY"]`), the limit may cut off tools from later toolkits. Increase `limit` or fetch each toolkit separately.
+</Callout>
+
+With direct execution, you manage [auth configs](/docs/auth-configuration/custom-auth-configs), [connect links](/docs/tools-direct/authenticating-tools), and [toolkit versioning](/docs/tools-direct/toolkit-versioning) yourself.
+
+## Migrating
+
+See the [migration guide](/docs/migration-guide/direct-to-sessions). Auth configs and connected accounts carry over.
+
+## Next steps
+
+<Cards>
+ <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build an agent with sessions" />
+ <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Toolkits, auth configs, and connected accounts" />
+ <Card icon={<Wrench />} title="Direct Tool Execution" href="/docs/tools-direct/executing-tools" description="Fetch and execute specific tools" />
+</Cards>
diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdx
index c50dcfd70..7411a6c52 100644
--- a/docs/content/docs/tools-direct/executing-tools.mdx
+++ b/docs/content/docs/tools-direct/executing-tools.mdx
@@ -6,7 +6,7 @@ llmGuardrails: "direct-execution"
---
<Callout type="info">
-If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle tool fetching, authentication, and execution automatically. See the [quickstart](/docs/quickstart) to build your first agent with sessions.
+If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle tool fetching, authentication, and execution automatically. See the [quickstart](/docs/quickstart) to get started, or [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) to understand the tradeoffs.
</Callout>
LLMs on their own can only do generation. Tool calling changes that by letting them interact with external services. Instead of just drafting an email, the model can call `GMAIL_SEND_EMAIL` to actually send it. The tool's results feed back to the LLM, closing the loop so it can decide, act, observe, and adapt.
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 9d02015c1..38b5f5713 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -188,9 +188,14 @@ export function mdxToCleanMarkdown(content: string): string {
while ((match = labelRegex.exec(tabsContent)) !== null) {
tabLabelMap[match[1]] = match[2];
}
- return '';
+ return '\n> Which should I use? See [Native Tools vs MCP](/docs/native-tools-vs-mcp)\n';
}
);
+ // Also handle IntegrationTabs without explicit tabs prop
+ result = result.replace(
+ /<IntegrationTabs(?![^>]*tabs=)[\s\S]*?>/g,
+ '\n> Which should I use? See [Native Tools vs MCP](/docs/native-tools-vs-mcp)\n'
+ );
// Convert IntegrationContent to labeled section
result = result.replace(