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 PromptBanner with copyable AI coding prompts to quickstart
Add a banner component to each quickstart integration flow with "Skills" link and "Copy prompt" button. Includes 6 detailed prompts (OpenAI Agents, Claude Agent SDK, Vercel AI × Native/MCP) with complete working code, install commands, rules, and verify checklists. The PromptBanner is stripped from .md output for LLM readers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmitha Mallesh committed
Mar 6, 2026 at 23:21 UTC
2ff8570e1472f700cb514d3ad351e4c59a618dd3
5 files changed
+844
-1
docs/components/quickstart/index.tsx
+1
@@ -1,3 +1,4 @@
1
export { FrameworkSelector, frameworks } from './framework-selector';
2
export { QuickstartFlow, FrameworkOption } from './quickstart-flow';
3
+export { PromptBanner } from './prompt-banner';
4
export type { Framework } from './framework-selector';
docs/components/quickstart/prompt-banner.tsx
new
+106
@@ -0,0 +1,106 @@
1
+'use client';
2
+
3
+import { useState, useRef, type ReactNode } from 'react';
4
+import { Copy, Check } from 'lucide-react';
5
+
6
+interface PromptBannerProps {
7
+ children: ReactNode;
8
+}
9
+
10
+export function PromptBanner({ children }: PromptBannerProps) {
11
+ const [copied, setCopied] = useState(false);
12
+ const contentRef = useRef<HTMLDivElement>(null);
13
+
14
+ const handleCopy = () => {
15
+ const text = contentRef.current?.innerText ?? '';
16
+ navigator.clipboard.writeText(text);
17
+ setCopied(true);
18
+ setTimeout(() => setCopied(false), 2000);
19
+ };
20
+
21
+ return (
22
+ <div className="not-prose mb-6">
23
+ <div className="relative flex items-center justify-between gap-6 overflow-hidden rounded-xl border border-fd-border bg-fd-card px-5 py-4">
24
+ {/* Ambient glow behind sparkle */}
25
+ <div
26
+ className="pointer-events-none absolute -left-4 top-1/2 -translate-y-1/2 h-32 w-32 rounded-full blur-2xl opacity-[0.12] dark:opacity-[0.15]"
27
+ style={{ background: 'var(--composio-orange)' }}
28
+ />
29
+
30
+ {/* Large 4-point star */}
31
+ <div className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 opacity-[0.15] dark:opacity-[0.15]">
32
+ <svg width="40" height="40" viewBox="0 0 40 40" fill="none">
33
+ <path
34
+ d="M20 4C20 4 22 16 20 20C18 16 20 4 20 4Z"
35
+ fill="var(--composio-orange)"
36
+ />
37
+ <path
38
+ d="M20 36C20 36 18 24 20 20C22 24 20 36 20 36Z"
39
+ fill="var(--composio-orange)"
40
+ />
41
+ <path
42
+ d="M4 20C4 20 16 18 20 20C16 22 4 20 4 20Z"
43
+ fill="var(--composio-orange)"
44
+ />
45
+ <path
46
+ d="M36 20C36 20 24 22 20 20C24 18 36 20 36 20Z"
47
+ fill="var(--composio-orange)"
48
+ />
49
+ </svg>
50
+ </div>
51
+
52
+ {/* Small 4-point star accent */}
53
+ <div className="pointer-events-none absolute left-11 top-1.5 opacity-[0.2] dark:opacity-[0.2]">
54
+ <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
55
+ <path
56
+ d="M7 1C7 1 7.8 5.5 7 7C6.2 5.5 7 1 7 1Z"
57
+ fill="var(--composio-orange)"
58
+ />
59
+ <path
60
+ d="M7 13C7 13 6.2 8.5 7 7C7.8 8.5 7 13 7 13Z"
61
+ fill="var(--composio-orange)"
62
+ />
63
+ <path
64
+ d="M1 7C1 7 5.5 6.2 7 7C5.5 7.8 1 7 1 7Z"
65
+ fill="var(--composio-orange)"
66
+ />
67
+ <path
68
+ d="M13 7C13 7 8.5 7.8 7 7C8.5 6.2 13 7 13 7Z"
69
+ fill="var(--composio-orange)"
70
+ />
71
+ </svg>
72
+ </div>
73
+
74
+ <p className="relative pl-10 text-[15px] text-fd-foreground/70">
75
+ Use skills or copy prompt to get started faster!
76
+ </p>
77
+
78
+ <div className="relative flex shrink-0 items-center gap-3">
79
+ <a
80
+ href="https://skills.sh/composiohq/skills/composio"
81
+ target="_blank"
82
+ rel="noopener noreferrer"
83
+ className="inline-flex items-center gap-2 rounded-lg border border-[var(--composio-orange)]/30 bg-transparent px-4 py-2 text-sm font-medium text-[var(--composio-orange)] transition-all hover:border-[var(--composio-orange)]/60 hover:bg-[var(--composio-orange)]/5"
84
+ >
85
+ Skills
86
+ <span aria-hidden="true">→</span>
87
+ </a>
88
+ <button
89
+ type="button"
90
+ onClick={handleCopy}
91
+ className={`inline-flex items-center gap-2 rounded-lg border px-4 py-2 text-sm font-medium transition-all duration-200 active:scale-[0.98] ${copied ? 'border-emerald-500/50 bg-emerald-500/10 text-emerald-500' : 'border-transparent bg-[var(--composio-orange)] text-white shadow-sm hover:brightness-110'}`}
92
+ >
93
+ {copied ? (
94
+ <Check className="h-4 w-4" strokeWidth={3} />
95
+ ) : (
96
+ <Copy className="h-4 w-4" />
97
+ )}
98
+ {copied ? 'Copied!' : 'Copy prompt'}
99
+ </button>
100
+ </div>
101
+ </div>
102
+ {/* Hidden prompt content for copy button */}
103
+ <div ref={contentRef} className="hidden">{children}</div>
104
+ </div>
105
+ );
106
+}
docs/content/docs/quickstart.mdx
+732
@@ -13,6 +13,122 @@ Build your first AI agent with Composio Tools. You'll create a [session](/docs/u
13
<IntegrationTabs>
14
<IntegrationContent value="native">
15
16
+<PromptBanner>
17
+# Add Composio tools to an OpenAI Agents app (Native Tools)
18
+
19
+Give your OpenAI Agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio. Composio handles authentication, tool discovery, and execution. You create a **session** for a user, get tools from that session, and pass them to your Agent.
20
+
21
+## Install
22
+
23
+```bash
24
+# Python
25
+pip install composio composio-openai-agents openai-agents python-dotenv
26
+
27
+# TypeScript
28
+npm install @composio/core @composio/openai-agents @openai/agents
29
+```
30
+
31
+## .env
32
+
33
+```
34
+COMPOSIO_API_KEY=your_composio_api_key
35
+OPENAI_API_KEY=your_openai_api_key
36
+```
37
+
38
+Get COMPOSIO_API_KEY from https://platform.composio.dev/settings
39
+
40
+## Complete working example
41
+
42
+### Python
43
+
44
+```python
45
+from dotenv import load_dotenv
46
+from composio import Composio
47
+from composio_openai_agents import OpenAIAgentsProvider
48
+from agents import Agent, Runner
49
+
50
+load_dotenv()
51
+
52
+composio = Composio(provider=OpenAIAgentsProvider())
53
+
54
+session = composio.create(user_id="user_123")
55
+tools = session.tools()
56
+
57
+agent = Agent(
58
+ name="Assistant",
59
+ instructions="You are a helpful assistant. Use Composio tools to take action.",
60
+ tools=tools,
61
+)
62
+
63
+result = Runner.run_sync(starting_agent=agent, input="Star the composiohq/composio repo on GitHub")
64
+print(result.final_output)
65
+```
66
+
67
+### TypeScript
68
+
69
+```typescript
70
+import "dotenv/config";
71
+import { Composio } from "@composio/core";
72
+import { OpenAIAgentsProvider } from "@composio/openai-agents";
73
+import { Agent, run } from "@openai/agents";
74
+
75
+const composio = new Composio({ provider: new OpenAIAgentsProvider() });
76
+
77
+const session = await composio.create("user_123");
78
+const tools = await session.tools();
79
+
80
+const agent = new Agent({
81
+ name: "Assistant",
82
+ instructions: "You are a helpful assistant. Use Composio tools to take action.",
83
+ tools,
84
+});
85
+
86
+const result = await run(agent, "Star the composiohq/composio repo on GitHub");
87
+console.log(result.finalOutput);
88
+```
89
+
90
+## Key concepts
91
+
92
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
93
+- **Provider**: Translates Composio tools into the framework's tool format. For OpenAI Agents, use `OpenAIAgentsProvider`.
94
+- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
95
+
96
+## Rules
97
+
98
+ALWAYS:
99
+- Initialize with `OpenAIAgentsProvider` as the provider
100
+- Create a session with a user ID before getting tools
101
+- Use `session.tools()` to get tools — this returns framework-ready tools
102
+- Store API keys in .env, load with dotenv
103
+
104
+NEVER:
105
+- Hardcode API keys in source code
106
+- Call tools directly without a session
107
+- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
108
+- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
109
+
110
+## Deprecated (DO NOT use)
111
+
112
+```
113
+# WRONG — old direct execution pattern
114
+tools = composio.tools.get(user_id, { toolkits: ['github'] })
115
+result = composio.tools.execute('GITHUB_STAR_REPO', {...})
116
+
117
+# WRONG — old package name
118
+from composio_core import Composio
119
+```
120
+
121
+## Verify before responding
122
+
123
+1. Is `OpenAIAgentsProvider` passed to `Composio()`?
124
+2. Is a session created with `composio.create(user_id)`?
125
+3. Are tools retrieved from `session.tools()`, not `composio.tools.get()`?
126
+4. Are API keys in .env, not hardcoded?
127
+5. Are imports from `composio` (Python) or `@composio/core` (TS)?
128
+
129
+Latest docs: https://docs.composio.dev/docs/quickstart
130
+</PromptBanner>
131
+
132
<Steps>
133
<Step>
134
<StepTitle>Install</StepTitle>
@@ -147,6 +263,137 @@ readline.close();
263
</IntegrationContent>
264
<IntegrationContent value="mcp">
265
266
+<PromptBanner>
267
+# Add Composio tools to an OpenAI Agents app (MCP)
268
+
269
+Give your OpenAI Agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio's hosted MCP server. No provider package needed — you connect directly to Composio's MCP endpoint. Composio handles authentication, tool discovery, and execution. You create a **session** for a user and pass the MCP connection to your Agent.
270
+
271
+## Install
272
+
273
+```bash
274
+# Python
275
+pip install composio openai-agents python-dotenv
276
+
277
+# TypeScript
278
+npm install @composio/core @openai/agents zod@3 dotenv
279
+```
280
+
281
+## .env
282
+
283
+```
284
+COMPOSIO_API_KEY=your_composio_api_key
285
+OPENAI_API_KEY=your_openai_api_key
286
+```
287
+
288
+Get COMPOSIO_API_KEY from https://platform.composio.dev/settings
289
+
290
+## Complete working example
291
+
292
+### Python
293
+
294
+```python
295
+from dotenv import load_dotenv
296
+from composio import Composio
297
+from agents import Agent, Runner, HostedMCPTool
298
+
299
+load_dotenv()
300
+
301
+composio = Composio()
302
+
303
+session = composio.create(user_id="user_123")
304
+
305
+agent = Agent(
306
+ name="Assistant",
307
+ instructions="You are a helpful assistant. Use Composio tools to take action.",
308
+ tools=[
309
+ HostedMCPTool(
310
+ tool_config={
311
+ "type": "mcp",
312
+ "server_label": "composio",
313
+ "server_url": session.mcp.url,
314
+ "require_approval": "never",
315
+ "headers": session.mcp.headers,
316
+ }
317
+ )
318
+ ],
319
+)
320
+
321
+result = Runner.run_sync(starting_agent=agent, input="Star the composiohq/composio repo on GitHub")
322
+print(result.final_output)
323
+```
324
+
325
+### TypeScript
326
+
327
+```typescript
328
+import "dotenv/config";
329
+import { Composio } from "@composio/core";
330
+import { Agent, run, hostedMcpTool } from "@openai/agents";
331
+
332
+const composio = new Composio();
333
+
334
+const session = await composio.create("user_123");
335
+
336
+const agent = new Agent({
337
+ name: "Assistant",
338
+ instructions: "You are a helpful assistant. Use Composio tools to take action.",
339
+ tools: [
340
+ hostedMcpTool({
341
+ serverLabel: "composio",
342
+ serverUrl: session.mcp.url,
343
+ headers: session.mcp.headers,
344
+ }),
345
+ ],
346
+});
347
+
348
+const result = await run(agent, "Star the composiohq/composio repo on GitHub");
349
+console.log(result.finalOutput);
350
+```
351
+
352
+## Key concepts
353
+
354
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
355
+- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers`. No `@composio/openai-agents` package needed.
356
+- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
357
+
358
+## Rules
359
+
360
+ALWAYS:
361
+- Use `session.mcp.url` and `session.mcp.headers` from the session — these are unique per session
362
+- Set `require_approval` to `"never"` in the Python tool_config
363
+- Create a session with a user ID before accessing `session.mcp`
364
+- Store API keys in .env, load with dotenv
365
+
366
+NEVER:
367
+- Hardcode MCP URLs or headers — they come from the session
368
+- Pass a provider to `Composio()` when using MCP mode (no provider needed)
369
+- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
370
+- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
371
+
372
+## Deprecated (DO NOT use)
373
+
374
+```
375
+# WRONG — old direct execution pattern
376
+tools = composio.tools.get(user_id, { toolkits: ['github'] })
377
+result = composio.tools.execute('GITHUB_STAR_REPO', {...})
378
+
379
+# WRONG — using a provider with MCP (not needed)
380
+composio = Composio(provider=OpenAIAgentsProvider())
381
+
382
+# WRONG — old package name
383
+from composio_core import Composio
384
+```
385
+
386
+## Verify before responding
387
+
388
+1. Is `Composio()` initialized WITHOUT a provider?
389
+2. Is a session created with `composio.create(user_id)`?
390
+3. Are `session.mcp.url` and `session.mcp.headers` used for the MCP connection?
391
+4. Is `require_approval` set to `"never"` in Python?
392
+5. Are API keys in .env, not hardcoded?
393
+
394
+Latest docs: https://docs.composio.dev/docs/quickstart
395
+</PromptBanner>
396
+
397
<Steps>
398
<Step>
399
<StepTitle>Install</StepTitle>
@@ -299,6 +546,149 @@ readline.close();
546
<IntegrationTabs>
547
<IntegrationContent value="native">
548
549
+<PromptBanner>
550
+# Add Composio tools to a Claude Agent SDK app (Native Tools)
551
+
552
+Give your Claude agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio. Composio handles authentication, tool discovery, and execution. You create a **session** for a user, get tools, wrap them in an SDK MCP server, and pass that server to ClaudeAgentOptions.
553
+
554
+## Install
555
+
556
+```bash
557
+# Python
558
+pip install composio composio-claude-agent-sdk claude-agent-sdk python-dotenv
559
+
560
+# TypeScript
561
+npm install @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk dotenv
562
+```
563
+
564
+## .env
565
+
566
+```
567
+COMPOSIO_API_KEY=your_composio_api_key
568
+ANTHROPIC_API_KEY=your_anthropic_api_key
569
+```
570
+
571
+Get COMPOSIO_API_KEY from https://platform.composio.dev/settings
572
+
573
+## Complete working example
574
+
575
+### Python
576
+
577
+```python
578
+import asyncio
579
+from dotenv import load_dotenv
580
+from composio import Composio
581
+from composio_claude_agent_sdk import ClaudeAgentSDKProvider
582
+from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, create_sdk_mcp_server, AssistantMessage, TextBlock
583
+
584
+load_dotenv()
585
+
586
+composio = Composio(provider=ClaudeAgentSDKProvider())
587
+
588
+session = composio.create(user_id="user_123")
589
+tools = session.tools()
590
+
591
+custom_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
592
+
593
+async def main():
594
+ options = ClaudeAgentOptions(
595
+ system_prompt="You are a helpful assistant. Use tools to complete tasks.",
596
+ permission_mode="bypassPermissions",
597
+ mcp_servers={"composio": custom_server},
598
+ )
599
+ async with ClaudeSDKClient(options=options) as client:
600
+ await client.query("Star the composiohq/composio repo on GitHub")
601
+ async for message in client.receive_response():
602
+ if isinstance(message, AssistantMessage):
603
+ for block in message.content:
604
+ if isinstance(block, TextBlock):
605
+ print(block.text, end="", flush=True)
606
+ print()
607
+
608
+asyncio.run(main())
609
+```
610
+
611
+### TypeScript
612
+
613
+```typescript
614
+import "dotenv/config";
615
+import { Composio } from "@composio/core";
616
+import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
617
+import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
618
+
619
+const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
620
+
621
+const session = await composio.create("user_123");
622
+const tools = await session.tools();
623
+
624
+const customServer = createSdkMcpServer({
625
+ name: "composio",
626
+ version: "1.0.0",
627
+ tools,
628
+});
629
+
630
+for await (const stream of query({
631
+ prompt: "Star the composiohq/composio repo on GitHub",
632
+ options: {
633
+ mcpServers: { composio: customServer },
634
+ permissionMode: "bypassPermissions",
635
+ },
636
+})) {
637
+ if (stream.type === "assistant") {
638
+ for (const block of stream.message.content) {
639
+ if (block.type === "text") process.stdout.write(block.text);
640
+ }
641
+ }
642
+}
643
+```
644
+
645
+## Key concepts
646
+
647
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
648
+- **Provider**: Translates Composio tools into the framework's tool format. For Claude Agent SDK, use `ClaudeAgentSDKProvider`.
649
+- **SDK MCP server**: Tools must be wrapped in an SDK MCP server via `create_sdk_mcp_server` / `createSdkMcpServer` before passing to `ClaudeAgentOptions.mcp_servers`. Do NOT pass tools directly.
650
+- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
651
+
652
+## Rules
653
+
654
+ALWAYS:
655
+- Initialize with `ClaudeAgentSDKProvider` as the provider
656
+- Create a session with a user ID before getting tools
657
+- Wrap tools in an SDK MCP server before passing to ClaudeAgentOptions
658
+- Use `async/await` — Claude Agent SDK is fully async
659
+- Store API keys in .env, load with dotenv
660
+
661
+NEVER:
662
+- Pass tools directly to ClaudeAgentOptions (must wrap in MCP server first)
663
+- Hardcode API keys in source code
664
+- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
665
+- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
666
+
667
+## Deprecated (DO NOT use)
668
+
669
+```
670
+# WRONG — old direct execution pattern
671
+tools = composio.tools.get(user_id, { toolkits: ['github'] })
672
+result = composio.tools.execute('GITHUB_STAR_REPO', {...})
673
+
674
+# WRONG — passing tools directly without MCP server wrapper
675
+options = ClaudeAgentOptions(tools=tools)
676
+
677
+# WRONG — old package name
678
+from composio_core import Composio
679
+```
680
+
681
+## Verify before responding
682
+
683
+1. Is `ClaudeAgentSDKProvider` passed to `Composio()`?
684
+2. Is a session created with `composio.create(user_id)`?
685
+3. Are tools wrapped in `create_sdk_mcp_server` / `createSdkMcpServer` before passing to options?
686
+4. Is the code using `async/await`?
687
+5. Are API keys in .env, not hardcoded?
688
+
689
+Latest docs: https://docs.composio.dev/docs/quickstart
690
+</PromptBanner>
691
+
692
<Steps>
693
<Step>
694
<StepTitle>Install</StepTitle>
@@ -457,6 +847,153 @@ readline.close();
847
</IntegrationContent>
848
<IntegrationContent value="mcp">
849
850
+<PromptBanner>
851
+# Add Composio tools to a Claude Agent SDK app (MCP)
852
+
853
+Give your Claude agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio's hosted MCP server. No provider package needed — you connect directly to Composio's MCP endpoint. Composio handles authentication, tool discovery, and execution. You create a **session** for a user and pass the MCP connection to ClaudeAgentOptions.
854
+
855
+## Install
856
+
857
+```bash
858
+# Python
859
+pip install composio claude-agent-sdk python-dotenv
860
+
861
+# TypeScript
862
+npm install @composio/core @anthropic-ai/claude-agent-sdk dotenv
863
+```
864
+
865
+## .env
866
+
867
+```
868
+COMPOSIO_API_KEY=your_composio_api_key
869
+ANTHROPIC_API_KEY=your_anthropic_api_key
870
+```
871
+
872
+Get COMPOSIO_API_KEY from https://platform.composio.dev/settings
873
+
874
+## Complete working example
875
+
876
+### Python
877
+
878
+```python
879
+import asyncio
880
+from dotenv import load_dotenv
881
+from composio import Composio
882
+from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
883
+
884
+load_dotenv()
885
+
886
+composio = Composio()
887
+
888
+session = composio.create(user_id="user_123")
889
+
890
+options = ClaudeAgentOptions(
891
+ system_prompt="You are a helpful assistant. Use tools to complete tasks.",
892
+ mcp_servers={
893
+ "composio": {
894
+ "type": "http",
895
+ "url": session.mcp.url,
896
+ "headers": session.mcp.headers,
897
+ }
898
+ },
899
+ permission_mode="bypassPermissions",
900
+)
901
+
902
+async def main():
903
+ async with ClaudeSDKClient(options) as client:
904
+ await client.query("Star the composiohq/composio repo on GitHub")
905
+ async for msg in client.receive_response():
906
+ if isinstance(msg, AssistantMessage):
907
+ for block in msg.content:
908
+ if isinstance(block, TextBlock):
909
+ print(block.text, end="", flush=True)
910
+ print()
911
+
912
+asyncio.run(main())
913
+```
914
+
915
+### TypeScript
916
+
917
+```typescript
918
+import "dotenv/config";
919
+import { Composio } from "@composio/core";
920
+import { query, type Options } from "@anthropic-ai/claude-agent-sdk";
921
+
922
+const composio = new Composio();
923
+
924
+const session = await composio.create("user_123");
925
+
926
+const options: Options = {
927
+ systemPrompt: "You are a helpful assistant. Use tools to complete tasks.",
928
+ mcpServers: {
929
+ composio: {
930
+ type: "http",
931
+ url: session.mcp.url,
932
+ headers: session.mcp.headers,
933
+ },
934
+ },
935
+ permissionMode: "bypassPermissions",
936
+};
937
+
938
+for await (const stream of query({
939
+ prompt: "Star the composiohq/composio repo on GitHub",
940
+ options,
941
+})) {
942
+ if (stream.type === "assistant") {
943
+ for (const block of stream.message.content) {
944
+ if (block.type === "text") process.stdout.write(block.text);
945
+ }
946
+ }
947
+}
948
+```
949
+
950
+## Key concepts
951
+
952
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
953
+- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers`. No `@composio/claude-agent-sdk` package needed.
954
+- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
955
+
956
+## Rules
957
+
958
+ALWAYS:
959
+- Use `session.mcp.url` and `session.mcp.headers` from the session — these are unique per session
960
+- Set MCP server type to `"http"` in the mcp_servers config
961
+- Set `permission_mode` to `"bypassPermissions"`
962
+- Use `async/await` — Claude Agent SDK is fully async
963
+- Store API keys in .env, load with dotenv
964
+
965
+NEVER:
966
+- Hardcode MCP URLs or headers — they come from the session
967
+- Pass a provider to `Composio()` when using MCP mode (no provider needed)
968
+- Import from `composio-core` (the package is `composio` for Python, `@composio/core` for TS)
969
+- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
970
+
971
+## Deprecated (DO NOT use)
972
+
973
+```
974
+# WRONG — old direct execution pattern
975
+tools = composio.tools.get(user_id, { toolkits: ['github'] })
976
+result = composio.tools.execute('GITHUB_STAR_REPO', {...})
977
+
978
+# WRONG — using a provider with MCP (not needed)
979
+composio = Composio(provider=ClaudeAgentSDKProvider())
980
+
981
+# WRONG — old package name
982
+from composio_core import Composio
983
+```
984
+
985
+## Verify before responding
986
+
987
+1. Is `Composio()` initialized WITHOUT a provider?
988
+2. Is a session created with `composio.create(user_id)`?
989
+3. Are `session.mcp.url` and `session.mcp.headers` used in the `mcp_servers` config?
990
+4. Is the MCP server type set to `"http"`?
991
+5. Is the code using `async/await`?
992
+6. Are API keys in .env, not hardcoded?
993
+
994
+Latest docs: https://docs.composio.dev/docs/quickstart
995
+</PromptBanner>
996
+
997
<Steps>
998
<Step>
999
<StepTitle>Install</StepTitle>
@@ -632,6 +1169,97 @@ readline.close();
1169
<IntegrationTabs>
1170
<IntegrationContent value="native">
1171
1172
+<PromptBanner>
1173
+# Add Composio tools to a Vercel AI SDK app (Native Tools)
1174
+
1175
+Give your Vercel AI agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio. Composio handles authentication, tool discovery, and execution. You create a **session** for a user, get tools from that session, and pass them to `streamText` or `generateText`. TypeScript only.
1176
+
1177
+## Install
1178
+
1179
+```bash
1180
+npm install @composio/core @composio/vercel ai @ai-sdk/anthropic
1181
+```
1182
+
1183
+## .env
1184
+
1185
+```
1186
+COMPOSIO_API_KEY=your_composio_api_key
1187
+ANTHROPIC_API_KEY=your_anthropic_api_key
1188
+```
1189
+
1190
+Get COMPOSIO_API_KEY from https://platform.composio.dev/settings
1191
+
1192
+## Complete working example
1193
+
1194
+```typescript
1195
+import "dotenv/config";
1196
+import { Composio } from "@composio/core";
1197
+import { VercelProvider } from "@composio/vercel";
1198
+import { anthropic } from "@ai-sdk/anthropic";
1199
+import { generateText } from "ai";
1200
+
1201
+const composio = new Composio({ provider: new VercelProvider() });
1202
+
1203
+const session = await composio.create("user_123");
1204
+const tools = await session.tools();
1205
+
1206
+const result = await generateText({
1207
+ model: anthropic("claude-sonnet-4-6"),
1208
+ tools,
1209
+ system: "You are a helpful assistant. Use Composio tools to take action.",
1210
+ prompt: "Star the composiohq/composio repo on GitHub",
1211
+ maxSteps: 10,
1212
+});
1213
+
1214
+console.log(result.text);
1215
+```
1216
+
1217
+## Key concepts
1218
+
1219
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
1220
+- **Provider**: Translates Composio tools into the framework's tool format. For Vercel AI, use `VercelProvider`.
1221
+- **streamText vs generateText**: Use `streamText` for streaming responses, `generateText` for single responses. Both accept Composio tools via the `tools` parameter.
1222
+- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
1223
+
1224
+## Rules
1225
+
1226
+ALWAYS:
1227
+- Initialize with `VercelProvider` as the provider
1228
+- Create a session with a user ID before getting tools
1229
+- Use `session.tools()` to get tools — this returns Vercel AI-compatible tools
1230
+- Use `streamText` or `generateText` from the `ai` package
1231
+- Set `maxSteps` to allow multi-step tool use (e.g., `maxSteps: 10`)
1232
+- Store API keys in .env, load with dotenv
1233
+
1234
+NEVER:
1235
+- Hardcode API keys in source code
1236
+- Call tools directly without a session
1237
+- Import from `composio-core` (the package is `@composio/core`)
1238
+- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
1239
+- Forget `maxSteps` — without it, the model won't execute tool calls
1240
+
1241
+## Deprecated (DO NOT use)
1242
+
1243
+```
1244
+// WRONG — old direct execution pattern
1245
+const tools = composio.tools.get(userId, { toolkits: ['github'] });
1246
+const result = composio.tools.execute('GITHUB_STAR_REPO', {...});
1247
+
1248
+// WRONG — missing maxSteps (model won't execute tool calls)
1249
+const result = await generateText({ model, tools, prompt });
1250
+```
1251
+
1252
+## Verify before responding
1253
+
1254
+1. Is `VercelProvider` passed to `Composio()`?
1255
+2. Is a session created with `composio.create(userId)`?
1256
+3. Are tools retrieved from `session.tools()`, not `composio.tools.get()`?
1257
+4. Is `maxSteps` set in `streamText` / `generateText`?
1258
+5. Are API keys in .env, not hardcoded?
1259
+
1260
+Latest docs: https://docs.composio.dev/docs/quickstart
1261
+</PromptBanner>
1262
+
1263
<Steps>
1264
<Step>
1265
<StepTitle>Install</StepTitle>
@@ -722,6 +1350,110 @@ readline.close();
1350
</IntegrationContent>
1351
<IntegrationContent value="mcp">
1352
1353
+<PromptBanner>
1354
+# Add Composio tools to a Vercel AI SDK app (MCP)
1355
+
1356
+Give your Vercel AI agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.) via Composio's hosted MCP server. No provider package needed — you connect directly to Composio's MCP endpoint using `@ai-sdk/mcp`. Composio handles authentication, tool discovery, and execution. TypeScript only.
1357
+
1358
+## Install
1359
+
1360
+```bash
1361
+npm install @composio/core ai @ai-sdk/anthropic @ai-sdk/mcp dotenv
1362
+```
1363
+
1364
+## .env
1365
+
1366
+```
1367
+COMPOSIO_API_KEY=your_composio_api_key
1368
+ANTHROPIC_API_KEY=your_anthropic_api_key
1369
+```
1370
+
1371
+Get COMPOSIO_API_KEY from https://platform.composio.dev/settings
1372
+
1373
+## Complete working example
1374
+
1375
+```typescript
1376
+import "dotenv/config";
1377
+import { Composio } from "@composio/core";
1378
+import { anthropic } from "@ai-sdk/anthropic";
1379
+import { createMCPClient } from "@ai-sdk/mcp";
1380
+import { generateText } from "ai";
1381
+
1382
+const composio = new Composio();
1383
+
1384
+const { mcp } = await composio.create("user_123");
1385
+
1386
+const client = await createMCPClient({
1387
+ transport: {
1388
+ type: "http",
1389
+ url: mcp.url,
1390
+ headers: mcp.headers,
1391
+ },
1392
+});
1393
+const tools = await client.tools();
1394
+
1395
+const result = await generateText({
1396
+ model: anthropic("claude-sonnet-4-6"),
1397
+ tools,
1398
+ system: "You are a helpful assistant. Use Composio tools to take action.",
1399
+ prompt: "Star the composiohq/composio repo on GitHub",
1400
+ maxSteps: 10,
1401
+});
1402
+
1403
+console.log(result.text);
1404
+await client.close();
1405
+```
1406
+
1407
+## Key concepts
1408
+
1409
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
1410
+- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers` via `@ai-sdk/mcp`. No `@composio/vercel` package needed.
1411
+- **Client lifecycle**: Always close the MCP client with `await client.close()` when done.
1412
+- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
1413
+
1414
+## Rules
1415
+
1416
+ALWAYS:
1417
+- Use `mcp.url` and `mcp.headers` from the session — destructure with `const { mcp } = await composio.create(userId)`
1418
+- Set transport type to `"http"` in createMCPClient
1419
+- Set `maxSteps` to allow multi-step tool use (e.g., `maxSteps: 10`)
1420
+- Close the MCP client when done: `await client.close()`
1421
+- Store API keys in .env, load with dotenv
1422
+
1423
+NEVER:
1424
+- Hardcode MCP URLs or headers — they come from the session
1425
+- Pass a provider to `Composio()` when using MCP mode (no provider needed)
1426
+- Import from `composio-core` (the package is `@composio/core`)
1427
+- Use `composio.tools.get()` or `composio.tools.execute()` — these are deprecated direct execution patterns
1428
+- Forget `maxSteps` — without it, the model won't execute tool calls
1429
+- Forget `await client.close()` — this leaks the MCP connection
1430
+
1431
+## Deprecated (DO NOT use)
1432
+
1433
+```
1434
+// WRONG — old direct execution pattern
1435
+const tools = composio.tools.get(userId, { toolkits: ['github'] });
1436
+const result = composio.tools.execute('GITHUB_STAR_REPO', {...});
1437
+
1438
+// WRONG — using a provider with MCP (not needed)
1439
+const composio = new Composio({ provider: new VercelProvider() });
1440
+
1441
+// WRONG — missing maxSteps (model won't execute tool calls)
1442
+const result = await generateText({ model, tools, prompt });
1443
+```
1444
+
1445
+## Verify before responding
1446
+
1447
+1. Is `Composio()` initialized WITHOUT a provider?
1448
+2. Is `mcp.url` and `mcp.headers` destructured from `composio.create(userId)`?
1449
+3. Is transport type `"http"` in `createMCPClient`?
1450
+4. Is `maxSteps` set in `streamText` / `generateText`?
1451
+5. Is `client.close()` called when done?
1452
+6. Are API keys in .env, not hardcoded?
1453
+
1454
+Latest docs: https://docs.composio.dev/docs/quickstart
1455
+</PromptBanner>
1456
+
1457
<Steps>
1458
<Step>
1459
<StepTitle>Install</StepTitle>
docs/lib/source.ts
+3
@@ -245,6 +245,9 @@ export function mdxToCleanMarkdown(content: string): string {
245
(_, name, content) => `### ${name}\n\n${content.trim()}`
246
);
247
248
+ // Strip PromptBanner and its children (UI-only copy-prompt widget)
249
+ result = result.replace(/<PromptBanner[\s\S]*?<\/PromptBanner>/g, '');
250
+
251
// Convert AIToolsBanner to plain text
252
result = result.replace(
253
/<AIToolsBanner\s*\/>/g,
docs/mdx-components.tsx
+2
-1
@@ -10,7 +10,7 @@ import { ImageZoom } from 'fumadocs-ui/components/image-zoom';
10
import { Heading } from '@/components/heading';
11
import { YouTube } from '@/components/youtube';
12
import { ProviderCard, ProviderGrid } from '@/components/provider-card';
13
-import { FrameworkSelector, QuickstartFlow, FrameworkOption } from '@/components/quickstart';
13
+import { FrameworkSelector, QuickstartFlow, FrameworkOption, PromptBanner } from '@/components/quickstart';
14
import { IntegrationTabs, IntegrationContent } from '@/components/quickstart/integration-tabs';
15
import { ToolTypeFlow, ToolTypeOption } from '@/components/tool-type-selector';
16
import { ConnectFlow, ConnectClientOption } from '@/components/connect-flow';
@@ -80,6 +80,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
80
FrameworkOption,
81
IntegrationTabs,
82
IntegrationContent,
83
+ PromptBanner,
84
ToolTypeFlow,
85
ToolTypeOption,
86
ConnectFlow,