@devries-cameron20 / composio Mirror · read-only / commits / f457fdf87
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 05:45 UTC

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

Two new comparison guides to help developers choose the right approach: - Native Tools vs MCP: provider packages vs MCP protocol, with token cost and latency tradeoffs linked to Anthropic/OpenAI sources - Sessions vs Direct Execution: meta tools vs direct tool fetching, covering discovery, dependency resolution, auth, workbench, and guidance Also adds cross-links from quickstart (IntegrationTabs), how-composio-works, migration guide, executing-tools, and common FAQ. Updates mdxToCleanMarkdown to inject "Which should I use?" link when processing IntegrationTabs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Mar 2, 2026 at 21:06 UTC f457fdf87f6f0c4d8b1c572933d56e7af6eae87b
9 files changed +363 -6
docs/components/quickstart/integration-tabs.tsx
+5 -1
@@ -1,6 +1,7 @@
1 'use client';
2
3 import Image from 'next/image';
4 +import Link from 'next/link';
5 import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
6 import { ReactNode } from 'react';
7
@@ -25,7 +26,7 @@ interface IntegrationTabsProps {
26 export function IntegrationTabs({ children, defaultValue, tabs = defaultTabs }: IntegrationTabsProps) {
27 return (
28 <Tabs defaultValue={defaultValue ?? tabs[0]?.value ?? 'native'} className="not-prose -mt-2">
28 - <div className="mb-5 flex justify-start">
29 + <div className="mb-5 flex items-center gap-3">
30 <TabsList>
31 {tabs.map((tab) => (
32 <TabsTrigger key={tab.value} value={tab.value} className="gap-2">
@@ -51,6 +52,9 @@ export function IntegrationTabs({ children, defaultValue, tabs = defaultTabs }:
52 </TabsTrigger>
53 ))}
54 </TabsList>
55 + <Link href="/docs/native-tools-vs-mcp" className="text-xs text-fd-muted-foreground hover:text-fd-foreground transition-colors">
56 + Which should I use?
57 + </Link>
58 </div>
59 {children}
60 </Tabs>
docs/content/docs/common-faq.mdx
+12
@@ -70,6 +70,18 @@ The User ID is how Composio identifies your end users. It maps each user to thei
70 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).
71 </Accordion>
72
73 +<Accordion title="What is the difference between an auth config and an MCP config in the dashboard?">
74 +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.
75 +
76 +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.
77 +
78 +**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.
79 +
80 +**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).
81 +
82 +See [Native Tools vs MCP](/docs/native-tools-vs-mcp) for a full comparison.
83 +</Accordion>
84 +
85 <Accordion title="What is an auth config?">
86 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.
87
docs/content/docs/how-composio-works.mdx
+6 -2
@@ -104,11 +104,15 @@ This keeps the agent's context window lean while still letting it handle operati
104
105 ## What to read next
106
107 -Start with the concepts in order, or jump to the quickstart if you want to build right away:
107 +Start with the concepts in order, or jump to the quickstart to build right away:
108
109 <Cards>
110 <Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
111 <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
112 <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, discovery, and execution" />
113 - <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent in 5 minutes" />
113 + <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent" />
114 </Cards>
115 +
116 +Deciding how to connect? See:
117 +- [Native Tools vs MCP](/docs/native-tools-vs-mcp) — SDK vs MCP servers
118 +- [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) — meta tools vs fetching specific tools
docs/content/docs/meta.json
+2
@@ -23,6 +23,8 @@
23 "using-custom-auth-configuration",
24 "webhook-verification",
25 "subscribing-to-connection-expiry-events",
26 + "native-tools-vs-mcp",
27 + "sessions-vs-direct-execution",
28 "---Features---",
29 "projects",
30 "single-toolkit-mcp",
docs/content/docs/migration-guide/direct-to-sessions.mdx
+1 -1
@@ -4,7 +4,7 @@ description: Move from direct tool execution to the sessions paradigm
4 keywords: [migrate, sessions, direct tools, upgrade]
5 ---
6
7 -This guide is for developers who are using Composio's **direct tool execution** pattern and want to migrate to **sessions**.
7 +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).
8
9 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.
10
docs/content/docs/native-tools-vs-mcp.mdx new
+139
@@ -0,0 +1,139 @@
1 +---
2 +title: Native Tools vs MCP
3 +description: When to use Composio's native SDK vs MCP servers
4 +keywords: [mcp, native tools, function calling, model context protocol, architecture, decision]
5 +---
6 +
7 +**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).
8 +
9 +**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.
10 +
11 +| | Native tools | MCP |
12 +|---|---|---|
13 +| **Setup** | [Provider package](/docs/providers) for your framework | SDK or just a URL |
14 +| **Intercepting tool calls** | Yes, you can log, retry, or require approval before each call | Limited, depends on what the MCP client supports |
15 +| **Context window** | You control what's loaded | Client loads all tools the server exposes |
16 +| **Latency** | SDK calls Composio API directly | MCP protocol adds overhead for tool list discovery and each execution |
17 +
18 +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.
19 +
20 +## Native tools
21 +
22 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
23 +<Tab value="Python">
24 +```python
25 +from composio import Composio
26 +from composio_openai import OpenAIProvider
27 +
28 +composio = Composio(provider=OpenAIProvider())
29 +session = composio.create(user_id="user_123")
30 +tools = session.tools()
31 +# Returns meta tools (COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS, etc.)
32 +# Agent discovers and executes tools at runtime
33 +```
34 +</Tab>
35 +<Tab value="TypeScript">
36 +```typescript
37 +import { Composio } from '@composio/core';
38 +import { OpenAIProvider } from '@composio/openai';
39 +
40 +const composio = new Composio({
41 + apiKey: process.env.COMPOSIO_API_KEY,
42 + provider: new OpenAIProvider(),
43 +});
44 +const session = await composio.create("user_123");
45 +const tools = await session.tools();
46 +// Returns meta tools (COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS, etc.)
47 +```
48 +</Tab>
49 +</Tabs>
50 +
51 +## MCP
52 +
53 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
54 +<Tab value="Python">
55 +```python
56 +from composio import Composio
57 +
58 +composio = Composio()
59 +session = composio.create(user_id="user_123")
60 +
61 +mcp_url = session.mcp.url
62 +mcp_headers = session.mcp.headers
63 +```
64 +</Tab>
65 +<Tab value="TypeScript">
66 +```typescript
67 +import { Composio } from '@composio/core';
68 +
69 +const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
70 +const session = await composio.create("user_123");
71 +
72 +const mcpUrl = session.mcp.url;
73 +const mcpHeaders = session.mcp.headers;
74 +```
75 +</Tab>
76 +</Tabs>
77 +
78 +Then pass `session.mcp.url` and `session.mcp.headers` to your framework:
79 +
80 +<Tabs items={['OpenAI Agents (Python)', 'Claude Agent SDK (Python)', 'Vercel AI SDK (TypeScript)']}>
81 +<Tab value="OpenAI Agents (Python)">
82 +```python
83 +from agents import Agent, HostedMCPTool
84 +
85 +agent = Agent(
86 + name="Assistant",
87 + tools=[
88 + HostedMCPTool(
89 + tool_config={
90 + "type": "mcp",
91 + "server_label": "composio",
92 + "server_url": session.mcp.url,
93 + "headers": session.mcp.headers,
94 + "require_approval": "never",
95 + }
96 + )
97 + ],
98 +)
99 +```
100 +</Tab>
101 +<Tab value="Claude Agent SDK (Python)">
102 +```python
103 +from claude_agent_sdk import ClaudeAgentOptions
104 +
105 +options = ClaudeAgentOptions(
106 + mcp_servers={
107 + "composio": {
108 + "type": "http",
109 + "url": session.mcp.url,
110 + "headers": session.mcp.headers,
111 + }
112 + },
113 +)
114 +```
115 +</Tab>
116 +<Tab value="Vercel AI SDK (TypeScript)">
117 +```typescript
118 +import { createMCPClient } from "@ai-sdk/mcp";
119 +
120 +const client = await createMCPClient({
121 + transport: {
122 + type: "http",
123 + url: mcp.url,
124 + headers: mcp.headers,
125 + },
126 +});
127 +const tools = await client.tools();
128 +```
129 +</Tab>
130 +</Tabs>
131 +
132 +See the [quickstart](/docs/quickstart) for full working examples.
133 +
134 +## Next steps
135 +
136 +<Cards>
137 + <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build an agent with sessions" />
138 + <Card icon={<Key />} title="Providers" href="/docs/providers" description="OpenAI, Anthropic, Vercel AI, LangChain" />
139 +</Cards>
docs/content/docs/sessions-vs-direct-execution.mdx new
+191
@@ -0,0 +1,191 @@
1 +---
2 +title: Sessions vs Direct Execution
3 +description: When to use session-based meta tools vs direct tool fetching and execution
4 +keywords: [session, direct execution, tool router, meta tools, architecture, decision]
5 +---
6 +
7 +**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.
8 +
9 +**Direct execution** gives your code specific tool schemas. You decide which tools to fetch, manage auth yourself, and call `tools.execute()` directly.
10 +
11 +Use sessions unless you need full control over which tools are available and when they run.
12 +
13 +| | Sessions | Direct execution |
14 +|---|---|---|
15 +| **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 |
16 +| **Context cost** | Only meta tools in context, app tools loaded on demand | Every tool schema you select is loaded upfront |
17 +| **Guidance** | Search returns recommended steps and common pitfalls alongside schemas | You get tool schemas only |
18 +| **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
19 +| **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) |
20 +| **[Workbench](/docs/workbench)** | Built in, large responses offloaded automatically | Not available |
21 +| **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 |
22 +| **Latency** | Multiple LLM turns (search, then execute) | Single call |
23 +
24 +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.
25 +
26 +## Sessions
27 +
28 +`composio.create()` returns [meta tools](/docs/tools-and-toolkits#meta-tools):
29 +
30 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
31 +<Tab value="Python">
32 +```python
33 +from composio import Composio
34 +from composio_openai import OpenAIProvider
35 +
36 +composio = Composio(provider=OpenAIProvider())
37 +session = composio.create(user_id="user_123")
38 +tools = session.tools()
39 +# Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
40 +# COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
41 +```
42 +</Tab>
43 +<Tab value="TypeScript">
44 +```typescript
45 +import { Composio } from '@composio/core';
46 +import { OpenAIProvider } from '@composio/openai';
47 +
48 +const composio = new Composio({
49 + apiKey: process.env.COMPOSIO_API_KEY,
50 + provider: new OpenAIProvider(),
51 +});
52 +const session = await composio.create("user_123");
53 +const tools = await session.tools();
54 +// Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
55 +// COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
56 +```
57 +</Tab>
58 +</Tabs>
59 +
60 +The agent discovers app tools through `COMPOSIO_SEARCH_TOOLS`:
61 +
62 +```
63 +User: "Create a GitHub issue for the login bug"
64 +
65 +> Agent calls COMPOSIO_SEARCH_TOOLS({ query: "create github issue" })
66 + Returns: GITHUB_CREATE_ISSUE schema + connection status
67 +
68 +> Agent calls COMPOSIO_MANAGE_CONNECTIONS({ toolkits: ["github"] })
69 + Returns: confirms connected (or auth link if not)
70 +
71 +> Agent calls COMPOSIO_MULTI_EXECUTE_TOOL({ tool: "GITHUB_CREATE_ISSUE", args: {...} })
72 + Returns: issue details
73 +
74 +Agent: "Created issue #42 on your-org/your-repo"
75 +```
76 +
77 +<Callout>
78 +`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.
79 +</Callout>
80 +
81 +### Configuration
82 +
83 +Restrict toolkits, set auth configs, pin connected accounts:
84 +
85 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
86 +<Tab value="Python">
87 +```python
88 +session = composio.create(
89 + user_id="user_123",
90 + toolkits=["github", "gmail"],
91 + auth_configs={"github": "ac_my_config"},
92 + connected_accounts={"gmail": "ca_work"},
93 +)
94 +```
95 +</Tab>
96 +<Tab value="TypeScript">
97 +```typescript
98 +import { Composio } from '@composio/core';
99 +const composio = new Composio({ apiKey: 'your_api_key' });
100 +// ---cut---
101 +const session = await composio.create("user_123", {
102 + toolkits: ["github", "gmail"],
103 + authConfigs: { github: "ac_my_config" },
104 + connectedAccounts: { gmail: "ca_work" },
105 +});
106 +```
107 +</Tab>
108 +</Tabs>
109 +
110 +See [Configuring Sessions](/docs/configuring-sessions) for details.
111 +
112 +## Direct execution
113 +
114 +Fetch tools by slug or toolkit. Pass them to your LLM or call `tools.execute()` without one.
115 +
116 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
117 +<Tab value="Python">
118 +```python
119 +from composio import Composio
120 +from composio_openai import OpenAIProvider
121 +
122 +composio = Composio(provider=OpenAIProvider())
123 +
124 +# Fetch specific tools
125 +tools = composio.tools.get(
126 + user_id="user_123",
127 + tools=["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"]
128 +)
129 +
130 +# Or by toolkit
131 +tools = composio.tools.get(
132 + user_id="user_123",
133 + toolkits=["GITHUB"],
134 + limit=50
135 +)
136 +
137 +# Execute without an LLM
138 +result = composio.tools.execute(
139 + "GITHUB_CREATE_ISSUE",
140 + user_id="user_123",
141 + arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"}
142 +)
143 +```
144 +</Tab>
145 +<Tab value="TypeScript">
146 +```typescript
147 +import { Composio } from '@composio/core';
148 +import { OpenAIProvider } from '@composio/openai';
149 +
150 +const composio = new Composio({
151 + apiKey: process.env.COMPOSIO_API_KEY,
152 + provider: new OpenAIProvider(),
153 +});
154 +
155 +// Fetch specific tools
156 +const tools = await composio.tools.get("user_123", {
157 + tools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"],
158 +});
159 +
160 +// Or by toolkit
161 +const allTools = await composio.tools.get("user_123", {
162 + toolkits: ["GITHUB"],
163 + limit: 50,
164 +});
165 +
166 +// Execute without an LLM
167 +const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
168 + userId: "user_123",
169 + arguments: { owner: "my-org", repo: "my-repo", title: "Fix login bug" },
170 +});
171 +```
172 +</Tab>
173 +</Tabs>
174 +
175 +<Callout type="warn">
176 +`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.
177 +</Callout>
178 +
179 +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.
180 +
181 +## Migrating
182 +
183 +See the [migration guide](/docs/migration-guide/direct-to-sessions). Auth configs and connected accounts carry over.
184 +
185 +## Next steps
186 +
187 +<Cards>
188 + <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build an agent with sessions" />
189 + <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Toolkits, auth configs, and connected accounts" />
190 + <Card icon={<Wrench />} title="Direct Tool Execution" href="/docs/tools-direct/executing-tools" description="Fetch and execute specific tools" />
191 +</Cards>
docs/content/docs/tools-direct/executing-tools.mdx
+1 -1
@@ -6,7 +6,7 @@ llmGuardrails: "direct-execution"
6 ---
7
8 <Callout type="info">
9 -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.
9 +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.
10 </Callout>
11
12 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.
docs/lib/source.ts
+6 -1
@@ -188,9 +188,14 @@ export function mdxToCleanMarkdown(content: string): string {
188 while ((match = labelRegex.exec(tabsContent)) !== null) {
189 tabLabelMap[match[1]] = match[2];
190 }
191 - return '';
191 + return '\n> Which should I use? See [Native Tools vs MCP](/docs/native-tools-vs-mcp)\n';
192 }
193 );
194 + // Also handle IntegrationTabs without explicit tabs prop
195 + result = result.replace(
196 + /<IntegrationTabs(?![^>]*tabs=)[\s\S]*?>/g,
197 + '\n> Which should I use? See [Native Tools vs MCP](/docs/native-tools-vs-mcp)\n'
198 + );
199
200 // Convert IntegrationContent to labeled section
201 result = result.replace(