@devries-cameron20 / composio-1 / commits / 2ff8570e1
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.

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,